Skill Authoring

Write skills that load at the right moment, teach what the model does not already know, and prove their own results.

When to Use

TRIGGER when:

• The user creates a skill directory, or asks to improve, review, or split an existing skill.
• A skill triggers too often, too rarely, or collides with a sibling skill.
• bun run lint-skills fails, or a skill must be registered in a plugin or the marketplace.
• The user wants a skillgrade eval for a skill.

Do not use when:

• The user is writing app docs, a README, a changelog, or marketing copy.
• The user is editing library or plugin source that is not a skill.

Reference Index

Only load a reference when its topic is in play.

Procedure

1. Scope the skill

• Write one sentence: "Load this when <concrete situation>, so the agent can <outcome>."
• List the sibling skills that could also match. Each one becomes a negative trigger.
• Split the skill if it covers two unrelated workflows. Merge it if it would be a one-paragraph stub.
• Ask the user at real judgement calls (scope, audience, which product to prefer). Do not ask about things you can read from the repo.

2. Write the frontmatter

---
name: my-skill                      # lowercase, hyphenated, equals the folder name
description: <what it does>. Use when <symptoms, APIs, file names, error strings>. Do not use for <case> (sibling-skill).
---

• The description is the only text the router sees. Put concrete triggers in it: command names, config keys, file names, exact error strings. Name the sibling skills in the negative clause.
• Keep it to one line and at most 1024 characters (lint enforces both).
• Optional when_to_use: is appended to description in Claude Code's skill listing. The combined text is truncated at 1,536 characters, so put the key use case first. Other agents ignore it, so never move the core trigger out of description.
• allowed-tools: only when the skill runs inline commands. Keep it minimal and read-only.

3. Write a lean body

Target fewer than about 250 lines. Use this order:

1. One-line purpose, plus a version line ("Checked against X 8.77, October 2026").
2. ## When to Use: TRIGGER bullets and a Do not use when list that points to sibling skills by name. Lint requires the ## When to Use heading.
3. ## Reference Index: a table of each file and when to load it, with "Only load a reference when its topic is in play."
4. ## Procedure: numbered steps. Inspect before you edit, and report findings before invasive changes.
5. ## Traps: the non-obvious failures. Skip basics the model already knows.
6. ## Verification: exact commands or checks that prove success.
7. ## Error Handling: exact error strings mapped to fixes.

Move dense tables, long code, and per-topic depth into references/<topic>.md, one level deep. Put fragile or repetitive logic in scripts/.

4. Fact-check everything

• Verify every command, flag, config key, and API against source or official docs. Prefer the package's --help, its type definitions, or its repo over memory.
• Tag time-sensitive facts with versions ("Capacitor 8.5+", "Xcode 27", "CLI 8.77"). Gate optional behavior on feature detection when the targets can be older.
• If you cannot verify a fact, write "check current docs" and do not guess. List any commands that do not exist but are commonly hallucinated.

5. Match command context

• Skill prose uses standard npm / npx examples. Capacitor and Capgo CLI examples use npx ...@latest.
• Use bun / bunx only for this repository's own development and CI commands, or in Bun-specific skills.
• When a skill edits another repository, tell the agent to read that repository's instructions and follow its package-manager policy.

6. Preserve secrets

When a skill edits user files, tell the agent never to replace user-provided tokens, keys, certificates, or passwords with placeholders unless asked. Placeholders are for new generic examples only. Do not suggest rotating secrets unless the user asks.

7. Register and validate (this repo)

Follow references/repo-layout.md: canonical folder in skills/, metadata.json, an entry in package.json skills, exposure through a plugin folder plus .claude-plugin/marketplace.json, then bun run sync-skills and bun run lint-skills.

8. Add an eval when behavior must not regress

Use skillgrade (eval.yaml + graders/). Prefer deterministic graders for structure. Use an LLM rubric only for qualitative judgement. Run it with bun run lint-skills-skillgrade, or ENABLE_SKILLGRADE=1 with an API key during lint.

Traps

• A vague description ("Helps with X") never triggers. A greedy one ("Use for anything about mobile") steals sibling requests.
• An index entry like "see references/" with no load condition makes the agent read everything or nothing. Always say when.
• Stale facts age faster than structure. Put the version line at the top so reviewers know what to re-check.
• Editing a mirrored copy under plugins/<plugin>/skills/ is wrong. Edit the canonical skills/<name>/, then sync.
• Inline !command`` snapshots run on every load. Keep them guarded (fs.existsSync), fast, short in output, and read-only.

Verification

1. bun run lint-skills passes. It checks the name against the folder, the description length, the ## When to Use heading, valid metadata.json, marketplace exposure, and byte-identical mirrors.
2. wc -l skills/<name>/SKILL.md is about 250 or less, and every file in references/ is named in the Reference Index.
3. A grep for each command in the skill matches the tool's --help or source.
4. Mental routing test: three prompts that should trigger the skill do, and one prompt for each sibling skill does not.

Error Handling