Shipping Skills

Shipping Skills

Overview

This skill is the end-to-end playbook for taking an Agent Skill from idea to a published, discoverable GitHub repo. It is opinionated and battle-tested: every step here exists because skipping it caused a real, avoidable problem.

The pipeline: design → write SKILL.md → triggers + evals → repo structure → name + discoverability → cross-file consistency → publish to GitHub → distribution → pre-publish review.

When to Use / Not Use

Use when: creating a new skill, writing or fixing a SKILL.md, structuring a skill repo, naming it, publishing to GitHub with releases, or getting it discovered.

Do not use for: writing application code, non-skill documentation, or general Git questions unrelated to shipping a skill.

1. Design first

Before writing anything, answer three questions:

• What cognitive/work failure does it fix, in one sentence? A skill that does "many things" triggers reliably for none.
• When should it fire? This becomes the description. Write down 5 example user phrases that should trigger it and 5 that should NOT.
• Single skill or a repo of skills? Standalone repo or fold into an existing one? Decide by mechanism + coupling + maintenance bandwidth, not vibes. A tool whose main use is independent of an existing repo belongs in its own repo. Don't put a tool inside a repo whose name implies a different mechanism (it misleads users about how it works).

2. Write the SKILL.md

Required frontmatter: name and description. Add version, license, metadata.tags.

The description is the single most important field — agents load only name + description at startup and use it to decide whether to activate the skill (progressive disclosure). So:

• Lead with user-intent trigger phrases ("second opinion", "fact-check this", "review my plan"), NOT internal-mechanism jargon ("heterogeneous multi-agent orchestration"). Users don't speak in your architecture's terms.
• Include a negative boundary: "Do not use for …". This stops the skill from grabbing tasks that belong to other skills.
• Keep the body focused; push large reference material into references/ and load on demand (progressive disclosure). A bloated SKILL.md wastes every session's context.

Body essentials: Overview · When to use/not · the core protocol/steps · examples · a verification checklist.

3. Triggers + evals

Ship an evals/ set from day one: ~10 should-trigger and ~10 should-not-trigger prompts. The boundary cases (prompts that look like they fit but belong to a neighboring skill) are the highest-value ones — they stop misfires. Re-run after every description edit; it's a regression test.

4. Repo structure