Agent Skills Crafter

Agent Skills are lightweight, open formats for extending AI agent capabilities with specialized knowledge and workflows. This document serves as a reference for the domain knowledge, architectural standards, and procedural guidelines required to create or modify Agent Skills effectively.

Core Principles

1. Discovery is Paramount (The Description): Agents use progressive disclosure. They only read the name and description to decide whether to activate a skill. Writing a highly optimized, intent-focused description is the most universally critical step in skill creation.
2. Progressive Disclosure: Keep SKILL.md concise (< 5000 tokens). Move detailed reference material to references/ and large templates/assets to assets/.
3. Domain Knowledge: Skills encapsulate procedural knowledge and rich context (e.g., project conventions, edge cases). Provide the "why" so the agent makes context-dependent decisions.
4. Eval-driven Iteration: Systematically test both whether the skill triggers (Trigger Rates) and whether it produces good results (Output Quality).
5. Scripting: Bundle reusable scripts in scripts/. Python scripts MUST follow PEP 723 inline dependency standards and be designed for non-interactive agent execution via uv run.

Skill Creation Workflow Guidelines