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

Fast Path

For a localized edit, do not ritualize it:

1. Inspect the skill and nearby conventions.
2. Edit the smallest thing that fixes the issue.
3. Validate structure and, when relevant, activation behavior.
4. 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

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:

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:

1. Choose: identify the mode, path, or workflow quickly.
2. Do: give imperative steps and decision points.
3. Show: include one excellent concrete example or template.
4. Guard: call out common mistakes, rationalizations, false positives, or edge cases.
5. Check: name the validation command, evidence, or expected result.

Prefer tables, checklists, templates, and input/output examples over explanatory prose.

Progressive Disclosure

Split content when:

• SKILL.md is 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:

1. Summary
2. Changes made or findings
3. Validation results
4. Open gaps