npm - @nguyenphp/antigravity-marketing - Versions diffs - 1.0.16 → 1.0.19 - Mend

@nguyenphp/antigravity-marketing 1.0.16 → 1.0.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (376) hide show

package/templates/.agent/skills/analytics-marketing/SKILL.md CHANGED Viewed

@@ -1,404 +1,252 @@
 ---
-name: analytics-tracking
-description: >
-  Design, audit, and improve analytics tracking systems that produce reliable,
-  decision-ready data. Use when the user wants to set up, fix, or evaluate
-  analytics tracking (GA4, GTM, product analytics, events, conversions, UTMs).
-  This skill focuses on measurement strategy, signal quality, and validation—
-  not just firing events.
+name: analytics-marketing
+description: Marketing analytics, attribution models, KPI tracking, dashboards, and data-driven decision making.
+allowed-tools: Read, Glob, Grep
 ---
-# Analytics Tracking & Measurement Strategy
+# Marketing Analytics
-You are an expert in **analytics implementation and measurement design**.
-Your goal is to ensure tracking produces **trustworthy signals that directly support decisions** across marketing, product, and growth.
-You do **not** track everything.
-You do **not** optimize dashboards without fixing instrumentation.
-You do **not** treat GA4 numbers as truth unless validated.
----
-## Phase 0: Measurement Readiness & Signal Quality Index (Required)
-Before adding or changing tracking, calculate the **Measurement Readiness & Signal Quality Index**.
-### Purpose
-This index answers:
-> **Can this analytics setup produce reliable, decision-grade insights?**
-It prevents:
-* event sprawl
-* vanity tracking
-* misleading conversion data
-* false confidence in broken analytics
----
-## 🔢 Measurement Readiness & Signal Quality Index
-### Total Score: **0–100**
-This is a **diagnostic score**, not a performance KPI.
+> Transform data into actionable marketing insights.
 ---
-### Scoring Categories & Weights
+## 1. Analytics Framework
-| Category                      | Weight  |
-| ----------------------------- | ------- |
-| Decision Alignment            | 25      |
-| Event Model Clarity           | 20      |
-| Data Accuracy & Integrity     | 20      |
-| Conversion Definition Quality | 15      |
-| Attribution & Context         | 10      |
-| Governance & Maintenance      | 10      |
-| **Total**                     | **100** |
+| Layer | Focus | Tools |
+|-------|-------|-------|
+| **Collection** | Tracking, tagging | GA4, GTM, Segment |
+| **Storage** | Data warehouse | BigQuery, Snowflake |
+| **Analysis** | Insights, patterns | Looker, Tableau |
+| **Action** | Optimization | A/B tools, personalization |
 ---
-### Category Definitions
+## 2. Key Marketing Metrics
-#### 1. Decision Alignment (0–25)
+### Acquisition Metrics
-* Clear business questions defined
-* Each tracked event maps to a decision
-* No events tracked “just in case”
+| Metric | Formula | Benchmark |
+|--------|---------|-----------|
+| **CAC** | Total acquisition cost / New customers | Industry varies |
+| **CPL** | Ad spend / Leads generated | $5-$50 B2B |
+| **CPC** | Ad spend / Clicks | $1-$5 avg |
+| **CPM** | (Ad spend / Impressions) × 1000 | $5-$15 avg |
----
+### Engagement Metrics
-#### 2. Event Model Clarity (0–20)
-* Events represent **meaningful actions**
-* Naming conventions are consistent
-* Properties carry context, not noise
----
+| Metric | Formula | Good |
+|--------|---------|------|
+| **Bounce rate** | Single-page sessions / Total sessions | < 40% |
+| **Pages/session** | Pageviews / Sessions | > 2 |
+| **Avg session duration** | Total duration / Sessions | > 2 min |
+| **Engagement rate** | Engaged sessions / Total sessions | > 50% |
-#### 3. Data Accuracy & Integrity (0–20)
+### Conversion Metrics
-* Events fire reliably
-* No duplication or inflation
-* Values are correct and complete
-* Cross-browser and mobile validated
----
-#### 4. Conversion Definition Quality (0–15)
-* Conversions represent real success
-* Conversion counting is intentional
-* Funnel stages are distinguishable
----
+| Metric | Formula | Good |
+|--------|---------|------|
+| **Conversion rate** | Conversions / Visitors | 2-5% |
+| **Lead-to-customer** | Customers / Leads | 10-20% |
+| **Cart abandonment** | Abandonments / Carts created | < 70% |
+| **Checkout abandonment** | Abandonments / Checkouts started | < 50% |
-#### 5. Attribution & Context (0–10)
+### Revenue Metrics
-* UTMs are consistent and complete
-* Traffic source context is preserved
-* Cross-domain / cross-device handled appropriately
+| Metric | Formula |
+|--------|---------|
+| **LTV** | ARPU × Customer lifetime |
+| **LTV:CAC** | LTV / CAC (target > 3:1) |
+| **ROAS** | Revenue / Ad spend |
+| **MER** | Revenue / Total marketing spend |
 ---
-#### 6. Governance & Maintenance (0–10)
+## 3. Attribution Models
-* Tracking is documented
-* Ownership is clear
-* Changes are versioned and monitored
+### Common Models
----
-### Readiness Bands (Required)
+| Model | How It Works | Best For |
+|-------|--------------|----------|
+| **Last click** | 100% to final touchpoint | Direct response |
+| **First click** | 100% to first touchpoint | Awareness |
+| **Linear** | Equal across all touchpoints | Long cycles |
+| **Time decay** | More weight to recent | B2B |
+| **Position-based** | 40-20-40 first/mid/last | Balanced |
+| **Data-driven** | ML-based allocation | High volume |
-| Score  | Verdict               | Interpretation                    |
-| ------ | --------------------- | --------------------------------- |
-| 85–100 | **Measurement-Ready** | Safe to optimize and experiment   |
-| 70–84  | **Usable with Gaps**  | Fix issues before major decisions |
-| 55–69  | **Unreliable**        | Data cannot be trusted yet        |
-| <55    | **Broken**            | Do not act on this data           |
+### Multi-Touch Attribution
-If verdict is **Broken**, stop and recommend remediation first.
+| Stage | Touchpoint Credit |
+|-------|-------------------|
+| **Awareness** | First-touch heavy |
+| **Consideration** | Mid-touch matters |
+| **Decision** | Last-touch heavy |
 ---
-## Phase 1: Context & Decision Definition
+## 4. Google Analytics 4 (GA4)
-(Proceed only after scoring)
+### Key Differences from UA
-### 1. Business Context
+| UA | GA4 |
+|----|-----|
+| Sessions | Events |
+| Bounce rate | Engagement rate |
+| Goals | Conversions |
+| Views | Data streams |
-* What decisions will this data inform?
-* Who uses the data (marketing, product, leadership)?
-* What actions will be taken based on insights?
+### Essential Events
----
+| Event | Purpose |
+|-------|---------|
+| **page_view** | Page tracking |
+| **purchase** | Revenue tracking |
+| **generate_lead** | Lead capture |
+| **sign_up** | Registration |
+| **begin_checkout** | Funnel start |
+| **add_to_cart** | E-commerce |
-### 2. Current State
+### Custom Dimensions
-* Tools in use (GA4, GTM, Mixpanel, Amplitude, etc.)
-* Existing events and conversions
-* Known issues or distrust in data
+| Dimension | Use Case |
+|-----------|----------|
+| **user_id** | Cross-device |
+| **membership_tier** | Segmentation |
+| **content_group** | Content analysis |
+| **experiment_id** | A/B testing |
 ---
-### 3. Technical & Compliance Context
+## 5. Dashboard Design
-* Tech stack and rendering model
-* Who implements and maintains tracking
-* Privacy, consent, and regulatory constraints
+### Marketing Dashboard Structure
----
+| Section | Metrics |
+|---------|---------|
+| **Overview** | Revenue, sessions, conversions |
+| **Acquisition** | Traffic sources, CAC, new users |
+| **Engagement** | Bounce rate, time on site |
+| **Conversion** | Conversion rate, funnel |
+| **Revenue** | ROAS, LTV, AOV |
-## Core Principles (Non-Negotiable)
+### Visualization Best Practices
-### 1. Track for Decisions, Not Curiosity
-If no decision depends on it, **don’t track it**.
+| Metric Type | Best Visual |
+|-------------|-------------|
+| **Trend over time** | Line chart |
+| **Comparison** | Bar chart |
+| **Composition** | Pie/stacked bar |
+| **Distribution** | Histogram |
+| **Relationship** | Scatter plot |
+| **KPIs** | Big numbers |
 ---
-### 2. Start with Questions, Work Backwards
-Define:
-* What you need to know
-* What action you’ll take
-* What signal proves it
-Then design events.
----
-### 3. Events Represent Meaningful State Changes
-Avoid:
-* cosmetic clicks
-* redundant events
-* UI noise
+## 6. Funnel Analysis
-Prefer:
+### Standard Marketing Funnel
-* intent
-* completion
-* commitment
+| Stage | Metrics |
+|-------|---------|
+| **Awareness** | Impressions, reach |
+| **Interest** | Clicks, site visits |
+| **Consideration** | Lead form starts, cart adds |
+| **Intent** | Form completions, checkouts |
+| **Purchase** | Transactions, revenue |
+| **Loyalty** | Repeat purchases, referrals |
----
-### 4. Data Quality Beats Volume
+### Funnel Metrics
-Fewer accurate events > many unreliable ones.
+| Metric | Formula |
+|--------|---------|
+| **Stage conversion** | Next stage / Current stage |
+| **Overall conversion** | Final stage / First stage |
+| **Drop-off rate** | 1 - Stage conversion |
+| **Funnel velocity** | Avg time between stages |
 ---
-## Event Model Design
-### Event Taxonomy
-**Navigation / Exposure**
-* page_view (enhanced)
-* content_viewed
-* pricing_viewed
-**Intent Signals**
-* cta_clicked
-* form_started
-* demo_requested
+## 7. Cohort Analysis
-**Completion Signals**
+### Cohort Types
-* signup_completed
-* purchase_completed
-* subscription_changed
+| Type | Example |
+|------|---------|
+| **Acquisition** | Users by signup month |
+| **Behavioral** | Users by first action |
+| **Demographic** | Users by segment |
-**System / State Changes**
+### Retention Cohort Table
-* onboarding_completed
-* feature_activated
-* error_occurred
+| Cohort | Week 0 | Week 1 | Week 2 | Week 3 |
+|--------|--------|--------|--------|--------|
+| Jan W1 | 100% | 45% | 30% | 25% |
+| Jan W2 | 100% | 42% | 28% | 22% |
+| Jan W3 | 100% | 48% | 32% | 27% |
 ---
-### Event Naming Conventions
-**Recommended pattern:**
-```
-object_action[_context]
-```
-Examples:
-* signup_completed
-* pricing_viewed
-* cta_hero_clicked
-* onboarding_step_completed
-Rules:
-* lowercase
-* underscores
-* no spaces
-* no ambiguity
+## 8. Marketing Mix Modeling (MMM)
----
-### Event Properties (Context, Not Noise)
-Include:
-* where (page, section)
-* who (user_type, plan)
-* how (method, variant)
-Avoid:
-* PII
-* free-text fields
-* duplicated auto-properties
----
-## Conversion Strategy
-### What Qualifies as a Conversion
-A conversion must represent:
-* real value
-* completed intent
-* irreversible progress
-Examples:
-* signup_completed
-* purchase_completed
-* demo_booked
-Not conversions:
-* page views
-* button clicks
-* form starts
----
-### Conversion Counting Rules
-* Once per session vs every occurrence
-* Explicitly documented
-* Consistent across tools
----
-## GA4 & GTM (Implementation Guidance)
-*(Tool-specific, but optional)*
-* Prefer GA4 recommended events
-* Use GTM for orchestration, not logic
-* Push clean dataLayer events
-* Avoid multiple containers
-* Version every publish
----
-## UTM & Attribution Discipline
-### UTM Rules
-* lowercase only
-* consistent separators
-* documented centrally
-* never overwritten client-side
-UTMs exist to **explain performance**, not inflate numbers.
----
-## Validation & Debugging
-### Required Validation
-* Real-time verification
-* Duplicate detection
-* Cross-browser testing
-* Mobile testing
-* Consent-state testing
-### Common Failure Modes
-* double firing
-* missing properties
-* broken attribution
-* PII leakage
-* inflated conversions
----
-## Privacy & Compliance
-* Consent before tracking where required
-* Data minimization
-* User deletion support
-* Retention policies reviewed
-Analytics that violate trust undermine optimization.
----
+### Purpose
-## Output Format (Required)
+- Measure channel effectiveness
+- Optimize budget allocation
+- Account for external factors
-### Measurement Strategy Summary
+### Variables
-* Measurement Readiness Index score + verdict
-* Key risks and gaps
-* Recommended remediation order
+| Type | Examples |
+|------|----------|
+| **Media** | TV, digital, OOH |
+| **Base** | Brand, distribution |
+| **External** | Seasonality, economy |
+| **Competition** | Competitor activity |
 ---
-### Tracking Plan
+## 9. A/B Test Analysis
-| Event | Description | Properties | Trigger | Decision Supported |
-| ----- | ----------- | ---------- | ------- | ------------------ |
+### Statistical Significance
----
+| Sample | Min Detectable Effect |
+|--------|----------------------|
+| 1,000 | 20%+ |
+| 10,000 | 5-10% |
+| 100,000 | 2-5% |
-### Conversions
+### Test Metrics
-| Conversion | Event | Counting | Used By |
-| ---------- | ----- | -------- | ------- |
+| Metric | Purpose |
+|--------|---------|
+| **Conversion rate** | Primary metric |
+| **Revenue/user** | Revenue impact |
+| **Confidence** | Statistical validity |
+| **P-value** | < 0.05 for significance |
 ---
-### Implementation Notes
+## 10. Reporting Cadence
-* Tool-specific setup
-* Ownership
-* Validation steps
+### Report Types
----
+| Report | Frequency | Audience |
+|--------|-----------|----------|
+| **Real-time** | Live | Operations |
+| **Daily** | Every day | Marketing team |
+| **Weekly** | Every week | Marketing leads |
+| **Monthly** | Every month | Leadership |
+| **Quarterly** | Every quarter | Executive |
-## Questions to Ask (If Needed)
+### Report Structure
-1. What decisions depend on this data?
-2. Which metrics are currently trusted or distrusted?
-3. Who owns analytics long term?
-4. What compliance constraints apply?
-5. What tools are already in place?
+| Section | Content |
+|---------|---------|
+| **Summary** | Key highlights, changes |
+| **Performance** | Metrics vs goals |
+| **Insights** | Why it happened |
+| **Actions** | What to do next |
 ---
-## Related Skills
-* **page-cro** – Uses this data for optimization
-* **ab-test-setup** – Requires clean conversions
-* **seo-audit** – Organic performance analysis
-* **programmatic-seo** – Scale requires reliable signals
----
+> **Remember:** Data without action is just noise. Always tie analytics to decisions and outcomes.

package/templates/.agent/skills/api-patterns/SKILL.md ADDED Viewed

@@ -0,0 +1,81 @@
+---
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+# API Patterns
+> API design principles and decision-making for 2025.
+> **Learn to THINK, not copy fixed patterns.**
+## 🎯 Selective Reading Rule
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+---
+## 📑 Content Map
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
+| `response.md` | Envelope pattern, error format, pagination | Response structure |
+| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
+| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
+| `versioning.md` | URI/Header/Query versioning | API evolution planning |
+| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
+| `rate-limiting.md` | Token bucket, sliding window | API protection |
+| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+---
+## 🔗 Related Skills
+| Need | Skill |
+|------|-------|
+| API implementation | `@[skills/backend-development]` |
+| Data structure | `@[skills/database-design]` |
+| Security details | `@[skills/security-hardening]` |
+---
+## ✅ Decision Checklist
+Before designing an API:
+- [ ] **Asked user about API consumers?**
+- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?**
+- [ ] **Planned versioning strategy?**
+- [ ] **Considered authentication needs?**
+- [ ] **Planned rate limiting?**
+- [ ] **Documentation approach defined?**
+---
+## ❌ Anti-Patterns
+**DON'T:**
+- Default to REST for everything
+- Use verbs in REST endpoints (/getUsers)
+- Return inconsistent response formats
+- Expose internal errors to clients
+- Skip rate limiting
+**DO:**
+- Choose API style based on context
+- Ask about client requirements
+- Document thoroughly
+- Use appropriate status codes
+---
+## Script
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |

package/templates/.agent/skills/api-patterns/api-style.md ADDED Viewed

@@ -0,0 +1,42 @@
+# API Style Selection (2025)
+> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
+## Decision Tree
+```
+Who are the API consumers?
+│
+├── Public API / Multiple platforms
+│   └── REST + OpenAPI (widest compatibility)
+│
+├── Complex data needs / Multiple frontends
+│   └── GraphQL (flexible queries)
+│
+├── TypeScript frontend + backend (monorepo)
+│   └── tRPC (end-to-end type safety)
+│
+├── Real-time / Event-driven
+│   └── WebSocket + AsyncAPI
+│
+└── Internal microservices
+    └── gRPC (performance) or REST (simplicity)
+```
+## Comparison
+| Factor | REST | GraphQL | tRPC |
+|--------|------|---------|------|
+| **Best for** | Public APIs | Complex apps | TS monorepos |
+| **Learning curve** | Low | Medium | Low (if TS) |
+| **Over/under fetching** | Common | Solved | Solved |
+| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
+| **Caching** | HTTP native | Complex | Client-based |
+## Selection Questions
+1. Who are the API consumers?
+2. Is the frontend TypeScript?
+3. How complex are the data relationships?
+4. Is caching critical?
+5. Public or internal API?