claude-code-arcane 1.0.0

package/skills/ai-seo/references/monitoring-guide.md

@@ -0,0 +1,208 @@
+# AI Visibility Monitoring Guide
+
+How to track whether your content is getting cited by AI search engines — and what to do when citations change.
+
+The honest truth: AI citation monitoring is immature. There's no Google Search Console equivalent for Perplexity or ChatGPT. Most tracking is manual today. This guide covers what works now and what to watch for as tooling matures.
+
+---
+
+## What You're Tracking
+
+**Goal:** Know when you appear in AI answers, for which queries, on which platforms — and detect changes before your traffic is affected.
+
+**The challenge:** Most AI search platforms don't give publishers visibility into their citation data. You're reverse-engineering your presence through manual testing and indirect signals.
+
+**Four things to track:**
+1. Citation presence — are you appearing at all?
+2. Citation consistency — do you appear most of the time or occasionally?
+3. Competitor citations — who else is cited for your target queries?
+4. Traffic signals — is AI-driven traffic changing?
+
+---
+
+## Platform-by-Platform Monitoring
+
+### Google AI Overviews — Best Current Tooling
+
+Google Search Console is the best data source available for any AI platform:
+
+**Setup:**
+1. Open Google Search Console → Performance → Search results
+2. Add filter: "Search type" → "AI Overviews"
+3. Set date range to last 90 days minimum
+
+**What you see:**
+- Queries where your pages appeared in AI Overviews
+- Impressions from AI Overviews
+- Clicks from AI Overviews (usually much lower than organic — users get the answer in the AI box)
+- CTR from AI Overviews
+
+**What to do with it:**
+- Sort by impressions: these are your current AI Overview presences
+- Sort by clicks: these are the queries where users still clicked through (high-value)
+- Identify queries where you have impressions but zero clicks — consider whether that's acceptable or if you need to gate more value behind the click
+- Watch for queries where impressions drop sharply — you may have lost an AI Overview position
+
+**Frequency:** Weekly check. Pull a CSV monthly for trend analysis.
+
+---
+
+### Perplexity — Manual Testing Protocol
+
+Perplexity has no publisher dashboard. Manual testing is the only reliable method.
+
+**Weekly test protocol:**
+1. Identify your 10-20 highest-priority target queries
+2. Search each query on perplexity.ai in an incognito window
+3. Check the Sources panel on the right side
+4. Record: cited (yes/no), position in sources (1st, 2nd, 3rd...), which page was cited
+
+**What to record in your tracking log:**
+
+| Date | Query | Cited? | Position | Cited URL | Top Competitor |
+|---|---|---|---|---|---|
+| 2026-03-06 | "how to reduce SaaS churn" | Yes | 2 | /blog/churn-reduction | competitor.com |
+| 2026-03-06 | "SaaS churn rate benchmark" | No | — | — | competitor.com |
+
+**Patterns to watch for:**
+- Same query cited 4/4 weeks → stable citation (protect it)
+- Citation appearing intermittently (2 out of 4 weeks) → fragile position (strengthen the page)
+- Consistent non-citation → gap to fill (page missing extractable patterns)
+
+**Frequency:** Weekly for top 10 queries. Monthly for the full list.
+
+---
+
+### ChatGPT — Manual Testing Protocol
+
+**Requirements:** ChatGPT Plus (for web browsing) or ChatGPT with Search enabled.
+
+**Test protocol:**
+1. Start a new conversation (fresh context window)
+2. Enable browsing / search mode
+3. Ask your target query as a natural question
+4. Check citations in the response
+5. Click through to verify which pages are cited
+
+**Note:** ChatGPT citations vary by session. The same query may cite different sources on consecutive days. This is by design — treat it as probabilistic. Your goal is to appear in the citation set, not to appear every time.
+
+**What to test:**
+- Exact keyword queries ("best email marketing software")
+- Natural question queries ("what's the best email marketing software for small teams?")
+- Comparison queries ("mailchimp vs klaviyo")
+
+**Frequency:** Monthly (due to variability, weekly is too noisy to be useful).
+
+---
+
+### Microsoft Copilot — Manual Testing Protocol
+
+Access at copilot.microsoft.com or via Edge sidebar.
+
+Same protocol as ChatGPT. Look for source cards that appear with citations. Copilot integrates Bing's index, so if your Bing presence is strong, Copilot citations follow.
+
+**Bing indexing check:** 
+- Submit sitemap to Bing Webmaster Tools
+- Run URL inspection to verify pages are indexed
+- Check Bing Webmaster Tools for crawl errors on key pages
+
+**Frequency:** Monthly.
+
+---
+
+## Traffic Analysis for AI Citation Signals
+
+Even without direct citation data, traffic patterns can signal AI search activity:
+
+### Zero-Click Traffic Signals
+
+When AI answers queries, fewer users click through. Watch for:
+
+**Impression growth + traffic decline:** If Google Search Console shows impressions growing for a keyword but organic clicks dropping, an AI Overview may be answering the query. You're being cited but not visited.
+
+**Query pattern in GSC:** If informational queries show impression growth but navigational/commercial queries stay flat, AI Overviews are likely answering the informational queries.
+
+### Direct Traffic Anomalies
+
+Some AI platforms (Claude, Gemini) show traffic as "direct" since users often copy/paste URLs rather than clicking. An increase in direct traffic to specific content pages (not your homepage) can signal AI-driven attention.
+
+### Referral Traffic from AI Platforms
+
+Perplexity, ChatGPT, and Claude all send some referral traffic when users click cited sources. Set up in Google Analytics 4:
+
+1. Create a custom dimension tracking referral source
+2. Filter for: `perplexity.ai`, `chat.openai.com`, `claude.ai`, `copilot.microsoft.com`
+3. Track monthly — expect low absolute numbers but high engagement (these visitors are already pre-qualified)
+
+---
+
+## Tracking Template
+
+**Weekly AI Citation Tracker (copy this structure):**
+
+```
+Week of: [DATE]
+
+GOOGLE AI OVERVIEWS (from Search Console):
+- New queries with AI Overview impressions: [list]
+- Queries that dropped out: [list]
+- Top performing query: [query] — [# impressions] impressions
+
+PERPLEXITY (manual tests):
+Query: [query 1] → Cited: Y/N → Position: [#] → Competitor: [domain]
+Query: [query 2] → Cited: Y/N → Position: [#] → Competitor: [domain]
+Query: [query 3] → Cited: Y/N → Position: [#] → Competitor: [domain]
+
+NOTABLE CHANGES:
+- [Describe any significant wins or losses]
+
+ACTIONS FROM LAST WEEK:
+- [What we optimized] → [Result this week]
+
+ACTIONS FOR NEXT WEEK:
+- [Page to optimize]: [Specific change to make]
+```
+
+---
+
+## When Citations Drop
+
+### Immediate Diagnostic
+
+If you notice a citation you had has disappeared:
+
+1. **Check robots.txt** — Did someone accidentally block an AI crawler? Check `yourdomain.com/robots.txt` and test each bot.
+
+2. **Check the page itself** — Did the page structure change? Was the definition block moved? Was the FAQ section deleted in an edit?
+
+3. **Check competitor pages** — Did a competitor publish a more extractable version of the same content? Search the query and see who now appears.
+
+4. **Check page performance** — Is the page load slower? Did it get added to a noindex? Did canonical tags change?
+
+5. **Check domain authority signals** — Did you lose significant backlinks? Authority drops can affect AI citations on competitive queries.
+
+### Response Playbook
+
+| Root cause | Fix |
+|---|---|
+| AI bot blocked | Update robots.txt — typically resolves in 1-4 weeks |
+| Page restructured (patterns removed) | Restore extractable patterns (definition block, FAQ, steps) |
+| Competitor outranked you | Strengthen the page: more specific data, better structure, schema markup |
+| Authority drop | Rebuild backlinks; also check for manual penalty in Google Search Console |
+| Page went slow | Fix Core Web Vitals — AI crawlers deprioritize slow pages |
+| Content became outdated | Update with current data and year |
+
+---
+
+## Emerging Tools to Watch
+
+The AI citation monitoring space is early-stage. Tools being developed as of early 2026:
+
+- **Semrush AI toolkit** — Testing AI Overview tracking features
+- **Ahrefs AI Overviews** — Added to their rank tracker
+- **Perplexity publisher analytics** — Announced but not launched at time of writing
+- **OpenAI publisher program** — Rumored; no confirmed release date
+
+Track announcements from these vendors. First-mover advantage on publisher analytics will be significant.
+
+**Until then:** Manual testing + Google Search Console is the most reliable stack available. Don't let perfect be the enemy of done — weekly manual testing surfaces 80% of what you need to know.

package/skills/ai-seo/references/optimization-playbook.md

@@ -0,0 +1,58 @@
+# Content Optimization for AI Citability
+
+## The Content Patterns That Get Cited
+
+These are the block types AI systems reliably extract. Add at least 2-3 per key page.
+
+See also `content-patterns.md` for ready-to-use templates for each pattern.
+
+### Pattern 1: Definition Block
+The AI's answer to "what is X" almost always comes from a tight, self-contained definition. Format:
+
+> **[Term]** is [concise definition in 1-2 sentences]. [One sentence of context or why it matters].
+
+Placed within the first 300 words of the page. No hedging, no preamble. Just the definition.
+
+### Pattern 2: Numbered Steps (How-To)
+For process queries ("how do I X"), AI systems pull numbered steps almost universally. Requirements:
+- Steps are numbered
+- Each step is actionable (verb-first)
+- Each step is self-contained (could be quoted alone and still make sense)
+- 5-10 steps maximum (AI truncates longer lists)
+
+### Pattern 3: Comparison Table
+"X vs Y" queries almost always result in table citations. Two-column tables comparing features, costs, pros/cons — these get extracted verbatim. Format matters: clean markdown table with headers wins.
+
+### Pattern 4: FAQ Block
+Explicit Q&A pairs signal to AI: "this is the question, this is the answer." Mark up with FAQPage schema. Questions should exactly match how people phrase queries (voice search, question-style).
+
+### Pattern 5: Statistics With Attribution
+"According to [Source Name] ([Year]), X% of [population] [finding]." This format is extractable because it has a complete citation. Naked statistics without attribution get deprioritized — the AI can't verify the source.
+
+### Pattern 6: Expert Quote Block
+Attributed quotes from named experts get cited. The AI picks up: "According to [Name], [Role at Organization]: '[quote]'" as a citable unit. Build in a few of these per key piece.
+
+## Rewriting for Extractability
+
+When optimizing existing content:
+
+1. **Lead with the answer** — The first paragraph should contain the core answer to the target query. Don't save it for the conclusion.
+2. **Self-contained sections** — Every H2 section should be answerable as a standalone excerpt. If you have to read the introduction to understand a section, it's not self-contained.
+3. **Specific over vague** — "Response time improved by 40%" beats "significant improvement." AI systems prefer citable specifics.
+4. **Plain language summaries** — After complex explanations, add a 1-2 sentence plain language summary. This is what AI often lifts.
+5. **Named sources** — Replace "experts say" with "[Researcher Name], [Year]." Replace "studies show" with "[Organization] found in their [Year] survey."
+
+## Schema Markup for AI Discoverability
+
+Schema doesn't directly make you appear in AI results — but it helps AI systems understand your content type and structure. Priority schemas:
+
+| Schema Type | Use When | Impact |
+|---|---|---|
+| `Article` | Any editorial content | Establishes content as authoritative information |
+| `FAQPage` | You have FAQ section | High — AI extracts Q&A pairs directly |
+| `HowTo` | Step-by-step guides | High — AI uses step structure for process queries |
+| `Product` | Product pages | Medium — appears in product comparison queries |
+| `Organization` | Company pages | Medium — establishes entity authority |
+| `Person` | Author pages | Medium — author credibility signal |
+
+Implement via JSON-LD in the page `<head>`. Validate at schema.org/validator.

package/skills/analytics-tracking/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: analytics-tracking
+description: "Set up, audit, and debug analytics tracking — GA4, GTM, event taxonomy, conversion tracking, and data quality for SaaS funnels."
+argument-hint: ""
+category: "marketing-strategy"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+# Analytics Tracking
+
+Expert analytics implementation — every meaningful action captured accurately, consistently, and actionably.
+
+## Before Starting
+
+If `marketing-context.md` exists, read it first. Then gather: current state (GA4/GTM setup, tech stack, CMP), business context (conversion actions, micro-conversions, paid campaigns), and goals (from scratch, audit, or debug).
+
+## How This Skill Works
+
+- **Mode 1: Set Up From Scratch** — Build tracking plan, implement GA4/GTM, define events, configure conversions
+- **Mode 2: Audit Existing** — Audit coverage, gap-fill, clean up data quality issues
+- **Mode 3: Debug Issues** — Structured debugging for missing events, mismatched numbers, GTM preview issues
+
+---
+
+## Event Taxonomy Design
+
+**Format:** `object_action` (snake_case, verb at end)
+
+| Good | Bad |
+|------|-----|
+| `form_submit` | `submitForm`, `FormSubmitted` |
+| `plan_selected` | `clickPricingPlan` |
+| `checkout_completed` | `purchase`, `checkoutDone` |
+
+**Rules:** Always `noun_verb`, lowercase + underscores only, consistent tense (`_started`, `_completed`, `_failed`).
+
+For the full SaaS event taxonomy catalog, standard parameters, and custom dimension recommendations, see [references/event-taxonomy-guide.md](references/event-taxonomy-guide.md).
+
+---
+
+## GA4 Setup
+
+1. Create property, add web data stream
+2. Configure Enhanced Measurement (keep page views, scrolls, outbound clicks, search)
+3. Add custom events via GTM data layer (preferred) or gtag
+4. Mark conversions (max 30 per property): `signup_completed`, `checkout_completed`, `demo_requested`
+
+---
+
+## GTM Setup
+
+Use data layer push pattern (most reliable):
+
+```javascript
+window.dataLayer.push({
+  event: 'signup_completed',
+  signup_method: 'email',
+  user_id: userId
+});
+```
+
+For full container structure, tag/trigger/variable patterns, and CSS selector click configuration, see [references/gtm-patterns.md](references/gtm-patterns.md).
+
+---
+
+## Cross-Platform Tracking
+
+### UTM Convention
+
+| Parameter | Convention | Example |
+|-----------|-----------|---------|
+| `utm_source` | Platform (lowercase) | `google`, `linkedin` |
+| `utm_medium` | Traffic type | `cpc`, `email`, `social` |
+| `utm_campaign` | Campaign ID | `q1-trial-push` |
+
+**Rule:** Never tag organic/direct traffic with UTMs.
+
+For attribution windows by platform, cross-domain tracking setup, and consent management impact, see [references/debugging-playbook.md](references/debugging-playbook.md).
+
+---
+
+## Data Quality
+
+Common issues: duplicate events (GTM + hardcoded gtag), bot traffic, consent mode gaps. Under GDPR, implement Advanced Consent Mode via GTM for modeled data. Expected consent rate: 60-75% EU, 85-95% US.
+
+For deduplication fixes, bot filtering, and consent mode configuration, see [references/debugging-playbook.md](references/debugging-playbook.md).
+
+---
+
+## Output Artifacts
+
+| Request | Output |
+|---------|--------|
+| Build tracking plan | Event taxonomy, GA4 config, GTM structure |
+| Audit tracking | Gap analysis, data quality scorecard (0-100) |
+| Set up GTM | Tag/trigger/variable config per event |
+| Debug missing events | Structured steps: GTM Preview + DebugView + Network tab |
+
+---
+
+## Related Skills
+
+- **campaign-analytics**: For analyzing performance. NOT for implementation.
+- **ab-test-setup**: For designing experiments. Events feed A/B tests.
+- **gdpr-dsgvo-expert**: For GDPR compliance. This skill covers consent mode implementation.

package/skills/analytics-tracking/references/debugging-playbook.md

@@ -0,0 +1,224 @@
+# Tracking Debug Playbook
+
+Step-by-step methodology for diagnosing and fixing analytics tracking issues.
+
+---
+
+## The Debug Mindset
+
+Analytics bugs are harder than code bugs because:
+1. They fail silently — no error thrown, just missing data
+2. They often only appear in production
+3. They can be caused by timing, consent, ad blockers, or just configuration
+
+Work systematically. Don't guess. Verify at each layer before moving to the next.
+
+---
+
+## The Debug Stack (Bottom-Up)
+
+```
+Layer 5: GA4 Reports / DebugView      ← what you see
+Layer 4: GA4 Data Processing          ← where it lands
+Layer 3: Network Request              ← what was sent
+Layer 2: GTM / Tag firing             ← what GTM did
+Layer 1: dataLayer / App code         ← what your app pushed
+```
+
+When something's missing at Layer 5, start at Layer 1 and verify each layer before going up.
+
+---
+
+## Tool Setup
+
+### GTM Preview Mode
+
+1. GTM → Preview (top right)
+2. Enter your site URL → Connect
+3. A blue bar appears at the bottom of your site: "Google Tag Manager"
+4. GTM Preview panel opens in a separate tab
+5. Perform the action you're debugging
+6. Check: did the expected tag fire?
+
+**Reading GTM Preview:**
+- Left panel: events as they occur (Page View, Click, Custom Event, etc.)
+- Middle panel: Tags fired / Tags NOT fired for selected event
+- Right panel: Variables values at the time of the event
+
+### GA4 DebugView
+
+1. GA4 → Admin → DebugView
+2. Enable debug mode via:
+   - GTM: add `debug_mode: true` to your GA4 Event tag parameters
+   - Extension: install "GA Debugger" Chrome extension
+   - URL parameter: add `?_gl=` or use GA4 debug parameter
+3. Perform actions on your site
+4. Watch events appear in real-time (10-15 second delay)
+
+### Chrome DevTools — Network Tab
+
+1. Open DevTools → Network
+2. Filter by: `collect` or `google-analytics` or `analytics`
+3. Perform the action
+4. Look for requests to `https://www.google-analytics.com/g/collect`
+5. Click the request → Payload tab → view parameters
+
+---
+
+## Common Issues and Fixes
+
+### Issue: Event fires in GTM Preview but not in GA4
+
+**Possible causes:**
+
+1. **Consent mode blocking** — user is in denied state
+   - Check: In GTM Preview, look at Variables → `Analytics Storage` — is it `denied`?
+   - Fix: Test with consent granted, or implement Advanced Consent Mode
+
+2. **Filters blocking data** — internal traffic filter is active
+   - Check: GA4 → Admin → Data Filters — is "Internal Traffic" filter active?
+   - Fix: Disable filter temporarily, test, then re-enable and exclude your IP correctly
+
+3. **Debug mode not enabled** — DebugView only shows debug-mode traffic
+   - Check: Is `debug_mode: true` parameter on the GA4 Event tag?
+   - Fix: Add it, or use the GA4 Debugger Chrome extension
+
+4. **Wrong property** — you're looking at a different GA4 property
+   - Check: Confirm Measurement ID in GTM matches the GA4 property you're viewing
+   - Fix: Compare `G-XXXXXXXXXX` in GTM vs. GA4 Data Stream settings
+
+5. **Duplicate GA4 configuration tags** — two config tags = double sessions + weird data
+   - Check: GTM → Tags → filter by "GA4 Configuration" — more than one?
+   - Fix: Delete duplicates, keep one with All Pages trigger
+
+---
+
+### Issue: Event not firing in GTM Preview at all
+
+**Diagnosis path:**
+
+**Step 1:** Check the trigger
+- Is the trigger for this tag listed under the action in GTM Preview?
+- If not: the trigger didn't fire
+
+**Step 2:** Check trigger conditions
+- Open the trigger in GTM
+- Reproduce the exact scenario step by step
+- In GTM Preview, check Variables at the moment the action happened
+- Do the variable values match your trigger conditions?
+
+**Step 3:** dataLayer issue (for Custom Event triggers)
+- In GTM Preview → select the relevant event in left panel → Variables tab
+- Scroll to find `event` — what's the value?
+- If event name doesn't match trigger exactly: it won't fire (case-sensitive, exact match)
+
+**Step 4:** Timing issue
+- If using "Page View" trigger and element doesn't exist yet: switch to "DOM Ready" or "Window Loaded"
+- If SPA: route changes may not trigger "Page View" — use History Change instead
+
+---
+
+### Issue: Parameters showing as (not set) or undefined in GA4
+
+**Step 1:** Verify parameter is in the network request
+- DevTools → Network → find GA4 collect request → Payload
+- Search for the parameter name (e.g., `plan_name`)
+- If not there: GTM variable isn't resolving correctly
+
+**Step 2:** Check the GTM variable
+- GTM Preview → find the event → Variables tab
+- Find the variable for this parameter (e.g., `DLV - plan_name`)
+- What's its value? If `undefined`: the dataLayer push didn't include this key, or key name is wrong
+
+**Step 3:** Check dataLayer push in your app code
+- DevTools → Console → type: `dataLayer.filter(e => e.event === 'your_event_name')`
+- Inspect the object — is the parameter key present and spelled correctly?
+
+**Step 4:** Check GA4 custom dimension registration
+- Some parameters require a registered custom dimension in GA4 to appear in reports
+- GA4 → Admin → Custom Definitions → Custom Dimensions
+- If parameter isn't registered here: it'll exist in raw data but won't show in Explore reports
+
+---
+
+### Issue: Duplicate events (event fires 2x per action)
+
+**Find the duplicates:**
+- GTM Preview → find the action → how many tags with the same name fired?
+- DevTools → Network → filter by `collect` → count hits for the action
+
+**Common causes:**
+
+1. **Enhanced Measurement + manual GTM tag**
+   - e.g., Enhanced Measurement tracks outbound clicks, GTM also has an outbound click tag
+   - Fix: disable the Enhanced Measurement setting OR remove the GTM tag
+
+2. **Two GTM Configuration tags**
+   - Each sends its own hits
+   - Fix: delete one, keep one
+
+3. **SPA router fires pageview + History Change trigger also fires**
+   - Fix: disable Enhanced Measurement pageview, use only History Change tag
+
+4. **Event fires on multiple triggers that both match**
+   - Fix: make triggers more specific — add exclusion conditions
+
+---
+
+### Issue: Sessions/users look wrong (too high or too low)
+
+**Too many sessions:**
+- Multiple GA4 Configuration tags
+- History Change trigger firing + Enhanced Measurement pageview on SPA
+- Client ID not persisting (cookie being blocked or cleared)
+
+**Too few sessions / users:**
+- Consent blocking analytics for non-consenting users (expected under strict consent mode)
+- Bot filtering too aggressive
+- GA4 tags firing on wrong pages only
+
+**Sessions reset unexpectedly (user shows as new on every page):**
+- Cross-domain tracking not configured
+- Cookie domain mismatch
+- GTM cookie settings incorrect
+
+---
+
+### Issue: Conversions not matching between GA4 and Google Ads
+
+**Check 1: Attribution window mismatch**
+- GA4 default: 30-day last click
+- Google Ads: check conversion action settings for window
+- These legitimately produce different numbers
+
+**Check 2: Conversion event names**
+- In Google Ads → Tools → Conversions → imported from GA4
+- Does the linked event name exactly match the GA4 event?
+
+**Check 3: Import is linked**
+- Google Ads → Tools → Linked Accounts → Google Analytics 4
+- Is the correct GA4 property linked and synced?
+- Sync can take 24-48 hours after changes
+
+**Check 4: Enhanced Conversions**
+- If GA4 uses a user_id or email parameter, Enhanced Conversions can improve matching
+- Google Ads → Conversions → Enhanced Conversions for Web → Enable
+
+---
+
+## Debug Checklist Template
+
+Use this for any new tracking issue:
+
+```
+[ ] Confirmed exact event name and parameters expected
+[ ] Verified app code is pushing to dataLayer (console: dataLayer)
+[ ] GTM Preview: trigger fires at correct moment
+[ ] GTM Preview: parameters resolve to correct values (not undefined)
+[ ] Network: GA4 collect request appears with correct payload
+[ ] GA4 DebugView: event appears within 30 seconds
+[ ] GA4 DebugView: parameters present and correct
+[ ] GA4 Reports: event appears (24-48h delay for standard reports)
+[ ] Consent check: tested with analytics consent granted
+[ ] Filter check: internal traffic filter not blocking test traffic
+```