Skill Writing

Skill Writing

Author a new skill that meets the authoring conventions the first time — wherever it lives: a skills collection, a project, or the user's personal setup. Conventions live in [references/conventions.md](references/conventions.md) — read it; it is the same file skill-auditing checks against.

Step 1 — Gather requirements

Before drafting, establish (ask when unstated — never invent):

• What task or domain does the skill cover?
• The concrete use cases, so the "Use when ..." triggers come from real

situations, not guesses.

• Where the skill lives: a collection's skills//, the project's

skill directory (.claude/skills//; .agents/skills// as the portable fallback), or the user's global skills directory. Recommend from context — an express collection task → the collection; a codify/retro handoff of a project procedure → that project; a personal workflow → global — and ask one question when unclear.

• Does it need executable scripts (deterministic ops only) or just

instructions?

• Any reference material or existing skill it relates to.

Step 2 — Name and collision-check

Propose a name in the right family (gerund for managed-unit tools, short for standalone acts — see conventions). Then check skills.sh:

npx skills find ""   # look for an exact @ match

An exact collision → report it with its install count and offer alternatives before continuing. The registry check applies to collection additions; elsewhere (project or personal), only avoid names already installed at the destination.

Step 3 — Draft

Create SKILL.md at the destination gathered in Step 1. Draft per conventions: frontmatter (name == directory, capability + "Use when" ≤1024 chars), body ≤100 lines with detail split into references/, English only, original content, numbered steps. Add scripts only for deterministic operations.

Step 4 — Scaffold acceptance

Write tests//README.md: scenarios plus mechanical checks (grep/regex/count/diff) that skill-testing can run. Design these with the skill, not after — if a rule can't be mechanically checked, either sharpen the SKILL.md or record it as needing human review. Every destination keeps the same discipline; place the plan where the destination keeps tests (default tests//README.md, or alongside a personal skill).

Step 5 — Review and verify

Present the draft and test plan for the user's review. On approval, verify with the skill-testing skill when installed. If skill-testing is not installed, leave the test plan as a manual checklist and mention the install option at most once.

Review checklist

| Check | Requirement | | --- | --- | | name == directory | frontmatter matches folder | | description shape | capability sentence + "Use when ..." ≤1024 chars | | body length | ≤100 lines; detail in references/ | | English only | no CJK anywhere | | triggers | derived from gathered use cases | | originality | authored here, nothing vendored | | acceptance | test plan with mechanical checks (default tests//README.md) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BCGen
• Source: BCGen/skills
• License: MIT
• Homepage: https://skills.sh/BCGen/skills

Install and usage instructions live in the source repository linked above.