skill-authoring
Skill authoring
A skill is a folder of instructions, scripts and resources that an agent discovers and uses to do something more accurately and efficiently, not "just a markdown file": it can hold scripts, assets and data the agent can discover, explore and manipulate, and in Claude Code its frontmatter has many configuration options, including registering dynamic hooks (see the frontmatter reference). The most effective skills use those options and the folder structure well. Most of the best ones began as a few lines and a single gotcha, then got better because people kept adding to them as Claude hit new edge cases. Start from the skills documentation and the example skills to customize.
Branch-triggered references and observable completion also draw on [mattpocock/skills, writing-for-agents]; pressure checks on [obra/superpowers, writing-skills]; navigation and routing negatives on [bgauryy/octocode, octocode-skills]. Official description requirements take precedence over source preferences.
Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]
| The job | Read |
|---|---|
| Choosing what the skill is: the nine categories, examples of each, finding gaps in a library | CATEGORIES.md |
Writing it: what to leave out, observable decisions, the Gotchas section and decision records, the description and persistent triggers, who may invoke it (disable-model-invocation, user-invocable) and namespaced commands, the folder, request modes and rule ids, goals over steps, decision authority, linter or guidance, rule files with Incorrect and Correct pairs ranked by impact, checking a compiled file against its sources, small topic files injected by kind, rules fetched at run time and their risk, a library reference skill, simplifying |
WRITING.md |
| Giving it code and state: scripts and helper libraries, scripts that feed an agent (deterministic JSON, exit codes, no clobbering, wrong-context failures, plug-in scanners, generated docs with a freshness gate), published primitives kept out of context, lint rules, setup config, user extensions kept in the project, memory, on-demand hooks, workflow files | SCRIPTS-AND-HOOKS.md |
| Author an audit skill with explicit evidence and persistence contracts, routing UI and telemetry execution to their domain owners | PROJECT-AUDITS.md |
| Sharing it: checked into the repo or a plugin marketplace, a public registry or a single public URL, an uploaded ZIP for Claude, a skill handed to an audience, skills and docs bundled inside a package, running a marketplace, composing skills (a missing dependency is a stop, a manual-only chain of skills) | DISTRIBUTION.md |
| Knowing how it does: logging usage, triggering, evals with and without the skill, frozen scenarios, blind A/B, hillclimbing and evidence-based session reflection with judgment, tooling and divergent lenses | MEASURING.md |
| Turning an owned course, webinar series, podcast or newsletter archive into a skill: the pilot, the source register and rights, lesson and reference layers, claim records, the question router, context budget, the eight answer tests, packaging and an honest status table | CONTENT-TO-SKILL.md |