skill-authoring
Skill Authoring
Use this as the working playbook for skill creation and maintenance. Start by choosing the job below. Load only the files needed for that job.
Done means the skill loads for the right requests, gives clear instructions without bloating context, and records source evidence when domain accuracy matters.
Agents see name and description before they see the body. The body loads only after the description matches the task. References, scripts, and assets load only when needed. Write for that loading order.
Choose the Job
| Job | Read first | Then use when needed |
|---|---|---|
| Create a small skill from scratch | workflows/create.md | templates/simple.md, templates/router.md, references/patterns.md |
| Build or update a skill from docs, project history, examples, failures, or multiple sources | workflows/synthesize.md | README.md, references/examples.md |
| Review or audit an existing skill | references/rules.md | references/examples.md, spec/specification.md |
| Check whether a skill activates and behaves correctly | workflows/test.md | workflows/debug.md when activation fails |
| Diagnose a skill that will not trigger or is ignored | workflows/debug.md | spec/specification.md, references/rules.md |
| Improve a skill from a concrete session failure | workflows/refine.md | references/rules.md, workflows/test.md |
| Verify format constraints | spec/specification.md | Tooling |
More from joshuadavidthomas/agent-skills
frontend-design-principles
Create polished, intentional frontend interfaces. Use this skill when building any UI — dashboards, admin panels, landing pages, marketing sites, or web applications. Routes to specialized guidance based on context.
17writing-clearly-and-concisely
Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.
13crafting-effective-readmes
Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
12reducing-entropy
Use when evaluating designs, reviewing code, or refactoring - measures success by total code in the final codebase, not effort to get there. Bias toward deletion.
10improving-prompts
Use when optimizing CLAUDE.md, AGENTS.md, custom commands, or skill files for Claude 4.5 models - applies documented Anthropic best practices systematically instead of inventing improvements
10diataxis
Structure, classify, and write documentation using the Diátaxis framework. Use when writing docs, README files, guides, tutorials, how-to guides, API references, or organizing documentation architecture. Also use when asked to improve documentation, restructure docs, decide what type of doc to write, or classify existing content. Covers tutorials, how-to guides, reference, and explanation.
8