Claude Code Skill Authoring — Building Reusable Agent Skills for Claude CLI

name: cut-release description: Use when cutting a release, publishing a new version, tagging a build, or preparing release notes. Walks through version bump, changelog, tag, and publish steps. —Yo```markdown #

name: cut-release description: Use when cutting a release, publishing a new version, tagging a build, or preparing release notes. Walks through version bump, changelog, tag, and publish steps. #

You are helping cut a release. Follow these steps in order… ```the current task, and loads that skill’s body. So the description is not a label — it’s a when-to-fire condition. Pack it with concrete triggers:> ❌ description: Release helper.

✅ description: Use when cutting a release, publishing a version, tagging a build, or writing release notes. Covers version bump, changelog generation, git tag, and publish.The first never fires because nothing in a real task matches “release helper.” The second fires the moment the user says “let’s ship 2.4.0.” If your skill exists but never activates, the description is the culprit — every time.## Writing the Body: A Procedure, Not an EssayThe body is the instructions Claude follows once the skill loads. Three rules:1. Be a procedure, not prose. Numbered steps the model executes in order beat paragraphs of context. “1. Bump the version in package.json. 2. Regenerate the changelog from commits since the last tag. 3. …”

2. State preconditions and gotchas inline. “Before tagging, confirm CI is green on main” — the kind of thing a human would know to check.
3. Point to heavy detail, don’t inline it. If the versioning policy is 800 words, put it in references/versioning.md and write “for the version-bump rules, read references/versioning.md.” That’s progressive disclosure, next.## Progressive Disclosure: Keep SKILL.md LightThe power move in skill authoring. SKILL.md should be small — the trigger plus an overview plus pointers. The heavy material lives in supporting files that load only when the task reaches them.Why it matters: the description and overview need to be cheap, because they’re scanned for routing. The detailed 2,000-word spec only belongs in context once the skill is actually engaged and the task needs that depth. A skill that inlines everything defeats the purpose — you’re back to CLAUDE.md-style bloat, just triggered differently.```markdown

Steps #

1. Bump version (see references/versioning.md for the semver rules)
2. Run scripts/changelog.sh to generate the draft
3. … Claude reads `references/versioning.md` only when it actually needs the rules, not on every load.## Worked Example: A Release Checklist Skillmarkdown

name: cut-release description: Use when cutting a release, publishing a version, or tagging a build. Covers version bump, changelog, tag, publish, and the green-CI precondition```markdown

Steps #

1. Bump version (see references/versioning.md for the semver rules)
2. Run scripts/changelog.sh to generate the draft
3. …

2. Bump it in package.json and any version constants.
3. Generate the changelog from commits since the last tag.
4. Open a release PR; wait for review.
5. After merge: tag, push the tag, publish.Report which step you sto```markdown
---
name: cut-release
description: Use when cutting a release, publishing a version, or tagging a build. Covers version bump, changelog, tag, publish, and the green-CI precondition.
---

You are cutting a release. Do NOT skip the precondition check.

PRECONDITION: confirm CI is green on main. If not, stop and report.

Steps:
1. Determine the new version (semver; see references/versioning.md).
2. Bump it in package.json and any version constants.
3. Generate the changelog from commits since the last tag.
4. Open a release PR; wait for review.
5. After merge: tag, push the tag, publish.

Report which step you stopped at if anything blocks.
```ent results = test-order or shared-state dependence.
2. Check for unawaited async, real timers, and fixed sleeps.
3. Check for shared mutable state between tests.
4. Only after locating the cause, propose the fix. Do not "add a retry."
```Note the embedded domain knowledge (the four usual causes) — that's institutional expertise, packaged so anyone triggers the senior engineer's mental checklist.## Common Authoring Mistakes- **Vague description.** The skill exists but never fires. Add concrete trigger phrases — the words a user actually types when they need it.
- **Everything in CLAUDE.md.** Situational procedures bloating every prompt. Move them to skills.
- **Inlining heavy detail.** A 2,000-word SKILL.md. Use progressive disclosure — point to `references/`.
- **Prose instead of procedure.** A skill that reads like an essay. Number th```markdown
---
name: debug-flaky-test
description: Use when a test passes sometimes and fails other times, or when investigating CI flakiness, intermittent failures, or race conditions in the suite.
---

You are diagnosing a flaky test. Flakiness is almost always one of:
shared state, timing/async, test-order dependence, or external resources.

1. Reproduce: run the test 20x in isolation and 20x with the full suite.
   Different results = test-order or shared-state dependence.
2. Check for unawaited async, real timers, and fixed sleeps.
3. Check for shared mutable state between tests.
4. Only after locating the cause, propose the fix. Do not "add a retry."
```shared environment:1. **A reliable host for team-shared, CI-invoked workflows.** Skills are version-controlled and run in CI too. **HTStack
** — Hong Kong VPS, low-latency mainland-China access, stable BGP. Same IDC that hosts dibi8.com. $5-12/month.2. **Cloud headroom for parallel runs.** **DigitalOcean
** — $200 free credit for 60 days, 14+ regions.3. **A skills bundle.** The fastest way to write great skills is to read great ones. We packaged five battle-tested skills as a $19 bundle on Gumroad — see the floating CTA in the corner — with the descriptions, progressive-disclosure structure, and bundled scripts already done right.## Related Reading- [Subagent vs MCP vs Skill](/resources/llm-frameworks/claude-code-subagent-vs-mcp-server-skill-agent-2026/) — the three-axis framework this completes.
- [Custom Agent Authoring](/resources/llm-frameworks/claude-code-custom-agent-authoring-guide-2026/) — the subagent-axis sibling to this guide.
- [AI Agent Skills 2026 Developer Guide](/resources/llm-frameworks/ai-agent-skills-2026-developer-guide/) — the broader skills ecosystem.
- [Subagent Patterns](/resources/llm-frameworks/claude-code-subagent-patterns-multi-agent-workflows-2026/) — how skills compose with delegated workers.## VerdictSkills are the cheapest, most underrated extension point — a directory with a markdown file that turns situational expertise into just-in-time context. The whole craft reduces to two things: a **description** packed with the real trigger phrases so it fires at the right moment, and **progressive disclosure** so it stays light until the task needs its depth. Write those two well and you've packaged a procedure your whole team — and every CI run — gets for free, exactly when it's relevant. That completes the trio: skill for knowledge, subagent for context, MCP server for capability.