Skill Marketing

Skill Marketing

Market an Agent Skill across skill marketplaces, registries, and directories using standard CLIs, automated audits, manifest generators, and metrics tracking.

Workflow

Follow this numbered script-first workflow step by step:

1. Audit Publishability: Run the publishability audit script against the target repository:

   python3 scripts/audit_skill.py --repo <target-path> --remote
   

   Fix every block finding before proceeding. If manifests (.claude-plugin/plugin.json, marketplace.json) or skills-lock.json are missing or inconsistent, run:

   python3 scripts/gen_manifests.py --repo <target-path> --tags <comma-separated-keywords>
   

2. Optimize Listing Surface: Audit and optimize metadata per references/listing-optimization.md:

   • Refine SKILL.md frontmatter description for trigger precision and ASO (≤1024 chars, "Use when...", keywords). Note: Rewriting frontmatter description changes agent trigger behavior — ask for user approval before applying changes.
   • Ensure README.md includes standard copy-pasteable installation commands (npx skills add, /plugin marketplace add).
   • Configure GitHub topics (claude-code, agent-skills, skills) and repository description via gh repo edit.
   • Verify trust signals: root LICENSE, .sha256 sidecars for bundled ZIPs, zero binary/obfuscated code.

3. Select Marketplace Surfaces: Read references/marketplace-catalog.md and evaluate target fit across the five supported distribution classes:

   • Class A (Scraped Indexes): Automatic discovery for public repositories with standard layout.
   • Class B (CLI Registries): skills.sh and LobeHub.
   • Class C (Plugin Marketplace): Built-in Claude Code plugin discovery via root manifests.
   • Class D (Curated Lists): Submit one PR to ComposioHQ/awesome-claude-skills when the skill fits.
   • Class E (Manual/Form): Prepare prefilled payloads for explainx.ai and Cursor. Do not add private, vendor-only, or framework-specific registries to the tracker.

4. Execute Distribution:

   • When autonomous execution is authorized, run:

     python3 scripts/distribute_skill.py --repo <target-path> --surfaces all --auto --tracker <tracker-path>
     

     Use --dry-run to preview probes without executing or writing.
   • Class A: Confirm public visibility, canonical layout, topics, and repository description. Record discovery readiness; do not claim a scraper listing without a direct returned result.
   • Class B: Follow references/cli-playbooks.md. Run the version and help probes before any publish attempt. Execute only a verb and arguments confirmed by help output. Run the pinned skills.sh discovery proof.
   • Class C: Confirm manifests and lockfile; record /plugin marketplace add <owner>/<repo>. This command is an install path, not proof of a public listing.
   • Class D: Follow references/curated-list-prs.md. Create one non-merge PR when the skill fits; record the returned PR URL immediately. Never merge or claim inclusion before maintainer review.
   • Class E: Prepare structured submission payloads for the human-gated forms and do not claim submission without direct evidence.

5. Initialize Tracker & Log Actions: Copy assets/submission-tracker.csv to the target repository root (or requested path). Validate it with:

   python3 scripts/validate_tracker.py --tracker <tracker-path> --expected-surfaces 14
   

   Record action status, exact returned URLs, and proof outputs for every catalog surface. Allowed statuses are verified, submitted, ready, blocked-human, blocked-auth, not-supported, failed, and initial todo.

6. Track Adoption Metrics: Run the tracking script to record Day 0 baseline metrics:

   python3 scripts/track_metrics.py --repo <owner/repo> --csv <target-path>/skill-marketing-metrics.csv
   

   Set weekly tracking review cadence per references/tracking.md. Never construct a listing URL from a guessed slug.

Hard Rules

• Audit Gate: Resolve all block findings in audit_skill.py before distributing to any marketplace.
• One Canonical Repo: Maintain one source repository per skill (skills/<name>/SKILL.md). Never fork or split repos per marketplace.
• Trust Signals: Ensure LICENSE is present and every bundled archive has a .sha256 sidecar file.
• CLI Verbs Pinning: Never assume unverified CLI publish commands. Always run <cli> --help to pin supported verbs first.
• Proof Honesty: Local proof commands show package/discovery fit. Never claim live listing, ranking, or approval unless verified remotely.

Output Format

When executing a marketing run, present results in this format:

1. Audit Summary: Table of findings (severity, id, message) and resolution steps.
2. Listing Optimization: Proposed SKILL.md description rewrite, GitHub topics, and trust signal checks.
3. Surface Selection: Selected marketplace surfaces grouped by Class (A–E) with fit rationale.
4. Action Execution & Proofs: Log of CLI commands run, PR URLs created, and local proof outputs.
5. Tracker Path: Location of initialized submission-tracker.csv.
6. Next Check-in: Scheduled Day 7 tracking date and baseline metrics snapshot.

Resources

• marketplace-catalog.md: Supported 14-surface marketplace taxonomy and fit gates.
• cli-playbooks.md: CLI verification and publication playbooks for skills.sh and LobeHub.
• curated-list-prs.md: Composio awesome-list PR submission playbook using gh CLI.
• listing-optimization.md: Frontmatter trigger ASO, README commands, and trust signals.
• tracking.md: Adoption metrics, skills.sh leaderboard checks, and KPI benchmarks.
• audit_skill.py: Automated publishability and hygiene audit script.
• gen_manifests.py: Claude plugin manifest and lockfile generator script.
• track_metrics.py: GitHub API and skills.sh metrics tracking script.
• tracker_contract.py: Shared tracker header and status enum, including not-supported.
• validate_tracker.py: Validates all tracker rows, statuses, and required URLs.
• distribute_skill.py: Runs safe discovery probes and writes evidence-backed autonomous statuses.