claude-code-arcane 1.0.0

package/skills/programmatic-seo/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: programmatic-seo
+description: "Build SEO-optimized pages at scale using templates and data — directory, location, comparison, integration, and persona pages."
+argument-hint: ""
+category: "marketing-seo"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# Programmatic SEO
+
+You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide value, and avoid thin content penalties.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Before designing a programmatic SEO strategy, understand:
+
+1. **Business Context**
+   - What's the product/service?
+   - Who is the target audience?
+   - What's the conversion goal for these pages?
+
+2. **Opportunity Assessment**
+   - What search patterns exist?
+   - How many potential pages?
+   - What's the search volume distribution?
+
+3. **Competitive Landscape**
+   - Who ranks for these terms now?
+   - What do their pages look like?
+   - Can you realistically compete?
+
+---
+
+## Core Principles
+
+### 1. Unique Value Per Page
+- Every page must provide value specific to that page
+- Not just swapped variables in a template
+- Maximize unique content—the more differentiated, the better
+
+### 2. Proprietary Data Wins
+Hierarchy of data defensibility:
+1. Proprietary (you created it)
+2. Product-derived (from your users)
+3. User-generated (your community)
+4. Licensed (exclusive access)
+5. Public (anyone can use—weakest)
+
+### 3. Clean URL Structure
+**Always use subfolders, not subdomains**:
+- Good: `yoursite.com/templates/resume/`
+- Bad: `templates.yoursite.com/resume/`
+
+### 4. Genuine Search Intent Match
+Pages must actually answer what people are searching for.
+
+### 5. Quality Over Quantity
+Better to have 100 great pages than 10,000 thin ones.
+
+### 6. Avoid Google Penalties
+- No doorway pages
+- No keyword stuffing
+- No duplicate content
+- Genuine utility for users
+
+---
+
+## The 12 Playbooks
+
+Templates, Curation, Conversions, Comparisons, Examples, Locations, Personas, Integrations, Glossary, Translations, Directory, Profiles.
+
+> See [references/playbooks.md](references/playbooks.md) for the full playbook table, pattern examples, and detailed implementation guides.
+
+---
+
+## Choosing Your Playbook
+
+| If you have... | Consider... |
+|----------------|-------------|
+| Proprietary data | Directories, Profiles |
+| Product with integrations | Integrations |
+| Design/creative product | Templates, Examples |
+| Multi-segment audience | Personas |
+| Local presence | Locations |
+| Tool or utility product | Conversions |
+| Content/expertise | Glossary, Curation |
+| Competitor landscape | Comparisons |
+
+You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
+
+---
+
+## Implementation Framework
+
+Five steps: (1) keyword pattern research and demand validation, (2) data source identification, (3) template design with uniqueness rules, (4) internal linking (hub-and-spoke), (5) indexation strategy.
+
+> See [references/playbooks.md](references/playbooks.md) for the complete 5-step implementation framework with details per step.
+
+---
+
+## Quality Checks
+
+Pre-launch: verify each page provides unique value, answers search intent, has unique titles/meta, proper heading structure, schema, connected internal links, and is in the XML sitemap.
+
+Post-launch: track indexation rate, rankings, traffic, engagement, conversion. Watch for thin content warnings, ranking drops, manual actions.
+
+---
+
+## Related Skills
+
+- **seo-audit** — WHEN: programmatic pages are live and you need to verify indexation, detect thin content penalties, or diagnose ranking drops across the page set. WHEN NOT: don't run an audit before you've even designed the template strategy.
+- **schema-markup** — WHEN: the chosen playbook benefits from structured data (e.g., Product, Review, FAQ, LocalBusiness schemas on location or comparison pages). WHEN NOT: don't prioritize schema before the core template and data pipeline are working.
+- **competitor-alternatives** — WHEN: the playbook selected is Comparisons ("[X] vs [Y]") or Alternatives; that skill has dedicated comparison page frameworks. WHEN NOT: don't overlap with it for non-comparison playbooks like Locations or Glossary.
+- **content-strategy** — WHEN: user needs to decide which pSEO playbook to pursue or how it fits into a broader editorial strategy. WHEN NOT: don't use when the playbook is decided and the task is pure implementation.
+- **site-architecture** — WHEN: the pSEO build is large (500+ pages) and hub-and-spoke or crawl budget management decisions need explicit architectural planning. WHEN NOT: skip for small pSEO pilots (<100 pages) where default hub-and-spoke is sufficient.
+- **marketing-context** — WHEN: always check `.claude/product-marketing-context.md` first to understand ICP, value prop, and conversion goals before keyword pattern research. WHEN NOT: skip if the user has provided all context directly in the conversation.
+
+---
+
+## Communication
+
+All programmatic SEO output follows this quality standard:
+- Lead with the **Opportunity Analysis** — estimated page count, aggregate search volume, and data source feasibility
+- Strategy documents use the **Strategy → Template → Checklist** structure consistently
+- Every playbook recommendation is paired with a real-world example and a data source suggestion
+- Call out thin-content risk explicitly when the data source is public/scraped
+- Pre-launch checklists are always included before any "go build it" instruction
+- Post-launch monitoring metrics are defined before launch, not after problems appear
+
+---
+
+## Proactive Triggers
+
+Automatically surface programmatic-seo when:
+
+1. **"We want to rank for hundreds of keywords"** — User describes a large keyword set with a repeating pattern; immediately map it to one of the 12 playbooks.
+2. **Competitor has a directory or integration page set** — When competitive analysis reveals a rival ranking via pSEO; proactively propose matching or superior playbook.
+3. **Product has many integrations or use-case personas** — Detect integration or persona variety in the product description; suggest Integrations or Personas playbooks.
+4. **Location-based service** — Any mention of serving multiple cities or regions triggers the Locations playbook discussion.
+5. **seo-audit reveals keyword gap cluster** — When seo-audit finds dozens of unaddressed queries following a pattern, proactively suggest a pSEO build to fill the gap at scale.
+
+---
+
+## Output Artifacts
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| Opportunity Analysis | Markdown table | Keyword patterns × estimated volume × data source × difficulty rating |
+| Playbook Selection Matrix | Table | If/then mapping of business context to recommended playbook with rationale |
+| Page Template Spec | Markdown with annotated sections | URL pattern, title/meta templates, content block structure, unique value rules |
+| Pre-Launch Checklist | Checkbox list | Content quality, technical SEO, internal linking, indexation gates |
+| Post-Launch Monitoring Plan | Table | Metrics to track × tools × alert thresholds × review cadence |

package/skills/programmatic-seo/references/playbooks.md

@@ -0,0 +1,72 @@
+# Programmatic SEO Playbooks & Implementation
+
+## The 12 Playbooks (Detailed)
+
+| Playbook | Pattern | Example |
+|----------|---------|---------|
+| Templates | "[Type] template" | "resume template" |
+| Curation | "best [category]" | "best website builders" |
+| Conversions | "[X] to [Y]" | "$10 USD to GBP" |
+| Comparisons | "[X] vs [Y]" | "webflow vs wordpress" |
+| Examples | "[type] examples" | "landing page examples" |
+| Locations | "[service] in [location]" | "dentists in austin" |
+| Personas | "[product] for [audience]" | "crm for real estate" |
+| Integrations | "[product A] [product B] integration" | "slack asana integration" |
+| Glossary | "what is [term]" | "what is pSEO" |
+| Translations | Content in multiple languages | Localized content |
+| Directory | "[category] tools" | "ai copywriting tools" |
+| Profiles | "[entity name]" | "stripe ceo" |
+
+## Implementation Framework
+
+### 1. Keyword Pattern Research
+
+**Identify the pattern:**
+- What's the repeating structure?
+- What are the variables?
+- How many unique combinations exist?
+
+**Validate demand:**
+- Aggregate search volume
+- Volume distribution (head vs. long tail)
+- Trend direction
+
+### 2. Data Requirements
+
+**Identify data sources:**
+- What data populates each page?
+- Is it first-party, scraped, licensed, public?
+- How is it updated?
+
+### 3. Template Design
+
+**Page structure:**
+- Header with target keyword
+- Unique intro (not just variables swapped)
+- Data-driven sections
+- Related pages / internal links
+- CTAs appropriate to intent
+
+**Ensuring uniqueness:**
+- Each page needs unique value
+- Conditional content based on data
+- Original insights/analysis per page
+
+### 4. Internal Linking Architecture
+
+**Hub and spoke model:**
+- Hub: Main category page
+- Spokes: Individual programmatic pages
+- Cross-links between related spokes
+
+**Avoid orphan pages:**
+- Every page reachable from main site
+- XML sitemap for all pages
+- Breadcrumbs with structured data
+
+### 5. Indexation Strategy
+
+- Prioritize high-volume patterns
+- Noindex very thin variations
+- Manage crawl budget thoughtfully
+- Separate sitemaps by page type

package/skills/programmatic-seo/scripts/url_pattern_generator.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+URL Pattern Generator for Programmatic SEO
+
+Generates URL patterns and page templates from a data source.
+Helps plan template-based page generation at scale.
+
+Usage:
+  python3 url_pattern_generator.py                    # Demo mode
+  python3 url_pattern_generator.py data.json          # From data file
+  python3 url_pattern_generator.py data.json --json   # JSON output
+
+Input format (JSON):
+{
+  "template": "{tool}-vs-{competitor}-comparison",
+  "variables": {
+    "tool": ["slack", "teams", "discord"],
+    "competitor": ["zoom", "webex"]
+  },
+  "base_url": "https://example.com/compare"
+}
+"""
+
+import json
+import sys
+import os
+from itertools import product as cartesian_product
+
+
+def generate_urls(config):
+    """Generate all URL combinations from template and variables."""
+    template = config["template"]
+    variables = config["variables"]
+    base_url = config.get("base_url", "https://example.com")
+
+    var_names = list(variables.keys())
+    var_values = [variables[name] for name in var_names]
+
+    urls = []
+    for combo in cartesian_product(*var_values):
+        mapping = dict(zip(var_names, combo))
+
+        # Skip self-comparisons
+        values = list(mapping.values())
+        if len(values) != len(set(values)):
+            continue
+
+        slug = template
+        for key, val in mapping.items():
+            slug = slug.replace("{" + key + "}", str(val).lower().replace(" ", "-"))
+
+        url = f"{base_url}/{slug}"
+        urls.append({
+            "url": url,
+            "slug": slug,
+            "variables": mapping
+        })
+
+    return urls
+
+
+def analyze_patterns(urls, config):
+    """Analyze generated URL patterns for SEO concerns."""
+    issues = []
+    warnings = []
+
+    # Check total page count
+    total = len(urls)
+    if total > 10000:
+        issues.append(f"Generating {total:,} pages — risk of thin content penalty. Consider narrowing variables.")
+    elif total > 1000:
+        warnings.append(f"Generating {total:,} pages — ensure each has unique, substantial content.")
+
+    # Check URL length
+    long_urls = [u for u in urls if len(u["url"]) > 75]
+    if long_urls:
+        warnings.append(f"{len(long_urls)} URLs exceed 75 chars — may truncate in SERPs.")
+
+    # Check for potential duplicate intent
+    template = config["template"]
+    var_names = list(config["variables"].keys())
+    if len(var_names) >= 2:
+        # Check if swapped variables create duplicate intent
+        # e.g., "slack-vs-zoom" and "zoom-vs-slack"
+        seen_pairs = set()
+        dupes = 0
+        for u in urls:
+            vals = tuple(sorted(u["variables"].values()))
+            if vals in seen_pairs:
+                dupes += 1
+            seen_pairs.add(vals)
+        if dupes > 0:
+            warnings.append(f"{dupes} URL pairs may have duplicate search intent (e.g., 'A vs B' and 'B vs A'). Consider canonicalizing.")
+
+    # Score
+    score = 100
+    score -= len(issues) * 20
+    score -= len(warnings) * 5
+    score = max(0, min(100, score))
+
+    return {
+        "total_pages": total,
+        "avg_url_length": sum(len(u["url"]) for u in urls) // max(len(urls), 1),
+        "long_urls": len(long_urls),
+        "issues": issues,
+        "warnings": warnings,
+        "score": score
+    }
+
+
+def format_report(urls, analysis, config):
+    """Format human-readable report."""
+    lines = []
+    lines.append("")
+    lines.append("=" * 60)
+    lines.append("  PROGRAMMATIC SEO — URL PATTERN REPORT")
+    lines.append("=" * 60)
+    lines.append("")
+    lines.append(f"  Template:    {config['template']}")
+    lines.append(f"  Base URL:    {config.get('base_url', 'https://example.com')}")
+    lines.append(f"  Variables:   {len(config['variables'])} ({', '.join(config['variables'].keys())})")
+    lines.append(f"  Total Pages: {analysis['total_pages']:,}")
+    lines.append(f"  Avg URL Len: {analysis['avg_url_length']} chars")
+    lines.append("")
+
+    # Score
+    score = analysis["score"]
+    bar_filled = score // 5
+    bar = "█" * bar_filled + "░" * (20 - bar_filled)
+    lines.append(f"  PATTERN SCORE: {score}/100")
+    lines.append(f"  [{bar}]")
+    lines.append("")
+
+    # Issues
+    if analysis["issues"]:
+        lines.append("  🔴 ISSUES:")
+        for issue in analysis["issues"]:
+            lines.append(f"     • {issue}")
+        lines.append("")
+
+    if analysis["warnings"]:
+        lines.append("  🟡 WARNINGS:")
+        for warn in analysis["warnings"]:
+            lines.append(f"     • {warn}")
+        lines.append("")
+
+    # Sample URLs
+    lines.append("  📋 SAMPLE URLS (first 10):")
+    for u in urls[:10]:
+        lines.append(f"     {u['url']}")
+    if len(urls) > 10:
+        lines.append(f"     ... and {len(urls) - 10} more")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+SAMPLE_CONFIG = {
+    "template": "{tool}-vs-{competitor}-comparison",
+    "variables": {
+        "tool": ["slack", "microsoft-teams", "discord", "zoom"],
+        "competitor": ["slack", "microsoft-teams", "discord", "zoom", "webex", "google-meet"]
+    },
+    "base_url": "https://example.com/compare"
+}
+
+
+def main():
+    use_json = "--json" in sys.argv
+    args = [a for a in sys.argv[1:] if a != "--json"]
+
+    if args and os.path.isfile(args[0]):
+        with open(args[0]) as f:
+            config = json.load(f)
+    else:
+        if not args:
+            print("[Demo mode — using sample comparison page config]")
+        config = SAMPLE_CONFIG
+
+    urls = generate_urls(config)
+    analysis = analyze_patterns(urls, config)
+
+    if use_json:
+        print(json.dumps({
+            "config": config,
+            "urls": urls,
+            "analysis": analysis
+        }, indent=2))
+    else:
+        print(format_report(urls, analysis, config))
+
+
+if __name__ == "__main__":
+    main()

package/skills/prompt-engineer-toolkit/README.md

@@ -0,0 +1,51 @@
+# Prompt Engineer Toolkit
+
+Production toolkit for evaluating and versioning prompts with measurable quality signals. Includes A/B testing automation and prompt history management with diffs.
+
+## Quick Start
+
+```bash
+# Run A/B prompt evaluation
+python3 scripts/prompt_tester.py \
+  --prompt-a-file prompts/a.txt \
+  --prompt-b-file prompts/b.txt \
+  --cases-file testcases.json \
+  --format text
+
+# Store a prompt version
+python3 scripts/prompt_versioner.py add \
+  --name support_classifier \
+  --prompt-file prompts/a.txt \
+  --author team
+```
+
+## Included Tools
+
+- `scripts/prompt_tester.py`: A/B testing with per-case scoring and aggregate winner
+- `scripts/prompt_versioner.py`: prompt history (`add`, `list`, `diff`, `changelog`) in local JSONL store
+
+## References
+
+- `references/prompt-templates.md`
+- `references/technique-guide.md`
+- `references/evaluation-rubric.md`
+
+## Installation
+
+### Claude Code
+
+```bash
+cp -R marketing-skill/prompt-engineer-toolkit ~/.claude/skills/prompt-engineer-toolkit
+```
+
+### OpenAI Codex
+
+```bash
+cp -R marketing-skill/prompt-engineer-toolkit ~/.codex/skills/prompt-engineer-toolkit
+```
+
+### OpenClaw
+
+```bash
+cp -R marketing-skill/prompt-engineer-toolkit ~/.openclaw/skills/prompt-engineer-toolkit
+```

package/skills/prompt-engineer-toolkit/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: prompt-engineer-toolkit
+description: "A/B test prompts, version them, and build reusable templates for marketing AI workflows. Covers evaluation, regression, and rollout."
+argument-hint: ""
+category: "marketing-strategy"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Prompt Engineer Toolkit
+
+## Overview
+
+Use this skill to move prompts from ad-hoc drafts to production assets with repeatable testing, versioning, and regression safety. It emphasizes measurable quality over intuition. Apply it when launching a new LLM feature that needs reliable outputs, when prompt quality degrades after model or instruction changes, when multiple team members edit prompts and need history/diffs, when you need evidence-based prompt choice for production rollout, or when you want consistent prompt governance across environments.
+
+## Core Capabilities
+
+- A/B prompt evaluation against structured test cases
+- Quantitative scoring for adherence, relevance, and safety checks
+- Prompt version tracking with immutable history and changelog
+- Prompt diffs to review behavior-impacting edits
+- Reusable prompt templates and selection guidance
+- Regression-friendly workflows for model/prompt updates
+
+## Key Workflows
+
+### 1. Run Prompt A/B Test
+
+Prepare JSON test cases and run:
+
+```bash
+python3 scripts/prompt_tester.py \
+  --prompt-a-file prompts/a.txt \
+  --prompt-b-file prompts/b.txt \
+  --cases-file testcases.json \
+  --runner-cmd 'my-llm-cli --prompt {prompt} --input {input}' \
+  --format text
+```
+
+Input can also come from stdin/`--input` JSON payload.
+
+### 2. Choose Winner With Evidence
+
+The tester scores outputs per case and aggregates:
+
+- expected content coverage
+- forbidden content violations
+- regex/format compliance
+- output length sanity
+
+Use the higher-scoring prompt as candidate baseline, then run regression suite.
+
+### 3. Version Prompts
+
+```bash
+# Add version
+python3 scripts/prompt_versioner.py add \
+  --name support_classifier \
+  --prompt-file prompts/support_v3.txt \
+  --author alice
+
+# Diff versions
+python3 scripts/prompt_versioner.py diff --name support_classifier --from-version 2 --to-version 3
+
+# Changelog
+python3 scripts/prompt_versioner.py changelog --name support_classifier
+```
+
+### 4. Regression Loop
+
+1. Store baseline version.
+2. Propose prompt edits.
+3. Re-run A/B test.
+4. Promote only if score and safety constraints improve.
+
+## Script Interfaces
+
+- `python3 scripts/prompt_tester.py --help`
+  - Reads prompts/cases from stdin or `--input`
+  - Optional external runner command
+  - Emits text or JSON metrics
+- `python3 scripts/prompt_versioner.py --help`
+  - Manages prompt history (`add`, `list`, `diff`, `changelog`)
+  - Stores metadata and content snapshots locally
+
+## Pitfalls, Best Practices & Review Checklist
+
+**Avoid these mistakes:**
+1. Picking prompts from single-case outputs — use a realistic, edge-case-rich test suite.
+2. Changing prompt and model simultaneously — always isolate variables.
+3. Missing `must_not_contain` (forbidden-content) checks in evaluation criteria.
+4. Editing prompts without version metadata, author, or change rationale.
+5. Skipping semantic diffs before deploying a new prompt version.
+6. Optimizing one benchmark while harming edge cases — track the full suite.
+7. Model swap without rerunning the baseline A/B suite.
+
+**Before promoting any prompt, confirm:**
+- [ ] Task intent is explicit and unambiguous.
+- [ ] Output schema/format is explicit.
+- [ ] Safety and exclusion constraints are explicit.
+- [ ] No contradictory instructions.
+- [ ] No unnecessary verbosity tokens.
+- [ ] A/B score improves and violation count stays at zero.
+
+## References
+
+- [references/prompt-templates.md](references/prompt-templates.md)
+- [references/technique-guide.md](references/technique-guide.md)
+- [references/evaluation-rubric.md](references/evaluation-rubric.md)
+- [README.md](README.md)
+
+## Evaluation Design
+
+Each test case should define:
+
+- `input`: realistic production-like input
+- `expected_contains`: required markers/content
+- `forbidden_contains`: disallowed phrases or unsafe content
+- `expected_regex`: required structural patterns
+
+This enables deterministic grading across prompt variants.
+
+## Versioning Policy
+
+- Use semantic prompt identifiers per feature (`support_classifier`, `ad_copy_shortform`).
+- Record author + change note for every revision.
+- Never overwrite historical versions.
+- Diff before promoting a new prompt to production.
+
+## Rollout Strategy
+
+1. Create baseline prompt version.
+2. Propose candidate prompt.
+3. Run A/B suite against same cases.
+4. Promote only if winner improves average and keeps violation count at zero.
+5. Track post-release feedback and feed new failure cases back into test suite.

package/skills/prompt-engineer-toolkit/references/evaluation-rubric.md

@@ -0,0 +1,14 @@
+# Evaluation Rubric
+
+Score each case on 0-100 via weighted criteria:
+
+- Expected content coverage: +weight
+- Forbidden content violations: -weight
+- Regex/format compliance: +weight
+- Output length sanity: +/-weight
+
+Recommended acceptance gates:
+
+- Average score >= 85
+- No case below 70
+- Zero critical forbidden-content hits