AI Skills Best Practices

Use this skill to build, review, or improve SKILL.md-based skills with strong triggering, clear workflows, and efficient context use.

Workflow

• Use the workflow graph in references/skill-workflow.dot as the canonical flow.

• Follow references/graphviz-conventions.dot for node shapes, labels, and edge styles.

• Keep workflows trigger-based and split into focused subgraphs rather than one giant flow.

• Render graphs with scripts/render_dot.py when you need a visual check.

Core Principles

• Keep SKILL.md concise; move heavy reference material into references/ .

• Optimize for triggering: description should emphasize when to use the skill.

• Use progressive disclosure: metadata -> SKILL.md -> references/scripts/assets.

• Choose the right degree of freedom: text, pseudocode, or scripts depending on fragility.

• Prefer reusable resources (scripts, templates) over repeated prose.

Build Workflow (Overview)

• Define 2-3 concrete use cases and the phrases that should trigger the skill.

• Identify reusable resources (scripts, references, assets).

• Initialize the skill (if new) with scripts/init_skill.py .

• Draft SKILL.md with tight frontmatter and imperative instructions.

• Add resources; keep SKILL.md lean and link to references.

• Test triggering and functional behavior; capture failures and iterate.

• Package with scripts/package_skill.py once validated.

Frontmatter Rules

• name : kebab-case, matches folder name.

• description : emphasize when to use the skill; include triggers and symptoms.

• Avoid workflow summaries in the description. Keep it short and specific.

• Do not include XML angle brackets.

File Structure Rules

• SKILL.md must be named exactly SKILL.md .

• Folder name must be kebab-case.

• Do not add README.md inside the skill.

Detailed Guidance

Read references/best-practices.md for:

• Triggering and description writing patterns

• Testing and iteration checklists

• Troubleshooting under/over-triggering

• When to split content into references or scripts

• Token and context budget guidance