joshuadavidthomas 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 |
Fast Path
For a localized edit, do not ritualize it:
- Inspect the skill and nearby conventions.
- Edit the smallest thing that fixes the issue.
- Validate structure and, when relevant, activation behavior.
- Report what changed and what remains uncertain.
Use the workflow files for new skills, source synthesis, debugging, testing, or any change that touches the skill's shape.
Cardinal Rules
| Rule | Why It Matters |
|---|---|
| Description has trigger keywords | Without them, the skill never activates |
| Description names capabilities and activation conditions, not steps | Agents may follow description shortcuts instead of loading the body |
| Description uses third person | It is injected as metadata, not spoken by the agent |
| Name matches directory | Required for skill loading |
| Critical instructions appear early | Long content may be skipped or deemphasized |
SKILL.md stays lean |
Runtime context is limited |
References are directly linked from SKILL.md |
Hidden chains are easy to miss |
| Source-backed guidance beats vibes | Real docs, history, fixes, and failures improve accuracy |
| Precision before addition | More files and prose often reduce reliability |
| Test activation before deployment | A skill that works but never triggers has zero value |
| Use agent-agnostic language by default | Skills should port across LLM agents unless intentionally provider-specific |
For the full impact-ranked rule list, read references/rules.md when reviewing, auditing, or tightening a skill.
Skill Shape
skill-name/
├── SKILL.md # Required entry point
├── README.md # Optional maintainer context for synthesized or complex skills
├── references/ # Optional focused docs loaded on demand
├── scripts/ # Optional executable helpers
└── assets/ # Optional templates, schemas, images, static files
Use this placement model:
| Content | Put it in |
|---|---|
| Frontmatter and core instructions | SKILL.md |
| Detailed optional guidance the agent may need | references/*.md |
| Deterministic repeatable operations | scripts/* |
| Templates, schemas, static examples | assets/* |
| Source inventory, trust level, decisions, gaps, changelog | README.md |
Provenance belongs in README.md unless the agent needs it to perform the task.
Description Requirements
The description decides whether the skill ever loads. Write it for discovery.
Use this formula:
description: Use when [triggering conditions] — [specific capabilities]. Handles [file types, contexts, symptoms, synonyms].
Good:
description: Use when working with PDF files — extracts text, fills forms, merges documents. Handles .pdf files, scanned PDFs, and form fields.
Bad:
description: Processes PDFs by first extracting text, then analyzing structure, then outputting results.
Include:
- words users actually say
- file types and extensions
- error messages or symptoms
- synonyms and alternate phrasings
- negative/positive trigger distinctions when false positives matter
Exclude:
- step-by-step workflow summaries
- implementation details
- first-person language
- generic claims like "helps with documents"
Writing SKILL.md Bodies
Write for an agent that can already reason. Do not teach basics. Provide the facts, constraints, examples, and checks that change behavior.
Use this shape by default:
- Choose: identify the mode, path, or workflow quickly.
- Do: give imperative steps and decision points.
- Show: include one excellent concrete example or template.
- Guard: call out common mistakes, rationalizations, false positives, or edge cases.
- Check: name the validation command, evidence, or expected result.
Prefer tables, checklists, templates, and input/output examples over explanatory prose.
Progressive Disclosure
| Layer | What | When Loaded | Target |
|---|---|---|---|
| 1 | name + description |
Always | Trigger-rich, concise |
| 2 | SKILL.md body |
When skill triggers | Path choice + core rules |
| 3 | references/, scripts/, assets/ |
On demand | Focused leaves with direct reasons |
Split content when:
SKILL.mdis becoming an encyclopedia- guidance is optional or domain-specific
- a reference has a clear "open when..." reason
- scripts can make a fragile task deterministic
Do not split content just to look organized.
Tooling
Script paths are relative to this skill directory.
Scaffold a skill:
python scripts/init.py my-skill
python scripts/init.py my-skill --router # for skills that route between sub-workflows
Validate a skill:
./scripts/validate.sh path/to/skill
Or use the official validator:
pip install skills-ref
skills-ref validate path/to/skill
Validation checks structure. It does not prove description quality, source coverage, or behavioral reliability.
Source Material
Vendored authoring approaches live under sources/ for deeper study. For this skill's source inventory, synthesis decisions, and gaps, read README.md.
Report Back
When modifying or reviewing a skill, report:
- Summary
- Changes made or findings
- Validation results
- Open gaps