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

Defining Scope & Trigger (Frontmatter)

• Determine the Scope: Focus on what the agent wouldn't know on its own.
• Scaffold: Create the directory (skill-name/SKILL.md). The template assets/skill_template.md can be used.
• Optimize the Description: Because agents use progressive disclosure, the description field determines whether a skill is triggered. Follow these key techniques:
  • Imperative phrasing: Frame it as an instruction directly to the agent (e.g., "Use this skill when...").