Optimize Skills

Optimizing Skills

Use this skill to create, review, or improve SKILL.md-based skills so they trigger correctly, stay concise, and execute reliably.

Invocation Notice

• Inform the user when this skill is being invoked by name: optimize-skills.

Critical Constraints

• Description must state when and why to invoke the skill — no workflow summaries, no "what it does."
• Don't duplicate reference content in SKILL.md; link to references/ instead.
• SKILL.md target: \ 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.

Progressive Disclosure Targets

• Metadata (name + description): small startup footprint, ideally ~100 tokens.
• SKILL.md: keep actionable and concise, target \ "Non-obvious decision or loop?" [label="yes"];

"Need to show process guidance?" -> "Use markdown (list/table/code)" [label="no"]; "Non-obvious decision or loop?" -> "Use small inline DOT flowchart" [label="yes"]; "Non-obvious decision or loop?" -> "Use markdown (list/table/code)" [label="no"]; }

- Use markdown lists/tables/code blocks by default.
- Add DOT only when decision logic or loops are easy to misapply.
- Avoid placeholder node labels; use concrete actions and conditions.
- Follow `references/graphviz-conventions.dot` for node shapes and labels.
- Keep flowcharts small and trigger-based; split large flows into focused subgraphs.

Render DOT to SVG with `scripts/render-dot.py`.
Output SVGs are written to the target skill's `assets/` directory.

```bash
scripts/render-dot.py skills/optimize-skills/references/skill-workflow.dot
scripts/render-dot.py skills/optimize-skills/SKILL.md
scripts/render-dot.py skills/optimize-skills/SKILL.md --force # overwrite existing SVGs

Output

SKILL.md Structure

skills/
  skill-name/
    SKILL.md      # Main reference (required)
    assets/       # (optional) Static reusable resources such as templates or figures
    references/   # (optional) On-demand documentation, organized by topic or variant
    scripts/      # (optional) Executable helpers for deterministic tasks;
                  # scripts should be self-contained or clearly declare dependencies,
                  # include clear errors, and handle edge cases.

Rules

• SKILL.md must be named exactly SKILL.md.
• Folder name must be kebab-case, matching the name in frontmatter.
• Do not add README.md inside the skill.
• YAML frontmatter must include name and description fields.
• name must be kebab-case and match the folder name.
• description should emphasize when to use the skill and include triggers/symptoms.
• Avoid workflow summaries in the description.
• Keep descriptions short and specific.
• Prefer ## When to Use / ## When Not to Use for trigger cues; do not add a dedicated trigger-scenarios section unless explicitly requested by the repo.
• Refer to assets/skill-template.md for a suggested (but easily modified) template structure.

Common Mistakes

• Summarizing workflow in description instead of stating actionable triggers and symptoms.
• Copying working trigger scenarios directly into the final skill instead of converting them into description and ## When to Use.
• Keeping workflows as one giant graph instead of splitting into trigger-based subgraphs.
• Repeating deep reference material in SKILL.md instead of linking to references/.
• Leaving scripts implicit: deterministic steps should be executable where possible.

References

• assets/skill-template.md for a suggested SKILL.md structure.
• references/best-practices.md: checklists, structure guidance, testing, and troubleshooting patterns.
• references/skills-search-optimization.md: description and trigger optimization rules.
• references/skill-workflow.dot: canonical workflow for this skill.
• references/graphviz-conventions.dot: DOT style and semantics for workflow diagrams.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahgraber
• Source: ahgraber/skills
• License: CC0-1.0

Install and usage instructions live in the source repository linked above.