An agent skill is a reusable package of instructions and resources that extends an agent with a specialized workflow. Skills keep procedural knowledge out of the global system prompt, so the agent can discover capabilities without carrying every procedure in its active context. section 2.3 section 2.6
Skills use progressive disclosure. The agent first sees lightweight metadata, then loads the full instruction file when a task matches, and opens bundled resources as the work requires them. The agent harness manages discovery and instruction injection, so accurate descriptions and reliable activation matter. section 2.3 section 7.2.1
A skill is a directory centered on SKILL.md:
- YAML frontmatter requires a name and description. The name should be short, stable, lowercase, and hyphenated; the description states both the capability and when to use it. section 2.3.1
- The Markdown body contains the procedure, such as steps, output schemas, validation rules, and examples. section 2.3.1
- Optional scripts, references, assets, and tests support deterministic operations, conditional background material, reusable templates, and testing. section 2.3.1
Listing 2.2 Content of the SKILL.md file for the git-conventional-commits skill
--- name: git-conventional-commits description: Generates standardized git commit messages following the conventional commits spec. Use this when the user asks to commit changes or "wraps up" a task. license: MIT metadata: version: "1.0.0" --- # Git Conventional Commits ## Instructions When the user asks to commit, follow these steps: 1. Identify the primary change in the code. 2. Categorize the change into one of these types: feat, fix, docs, style, refactor, perf, test, or chore. 3. Format the message as: `<type>(<scope>): <description>` ## Examples - feat(auth): add Google OAuth support - fix(ui): resolve alignment issue on mobile
This SKILL.md combines an activation description with a procedure for producing conventional commit messages. section 2.3.1
To create a skill, write SKILL.md and place its directory where the target harness scans. For example, Claude Code scans .claude/skills/ in a project or ~/.claude/skills/ globally; compatible platforms may use .agents/skills/ or ~/.agents/skills/. Depending on the harness, a user can invoke a skill explicitly with slash syntax or let a matching request activate it. section 2.5.2
Standardizing meeting notes
A project-notetaker skill can trigger on raw meeting notes and instruct the agent to produce a title, attendees, key decisions, and an action-item table with task, owner, and due date. The description selects the workflow; the body supplies the output structure. section 2.5.2
A skill is useful for a repeatable CLI procedure whose consequences matter: it can specify allowed commands, their order, how to interpret output, and when to ask for confirmation. It is not required for an agent to use CLI tools. section 4.3.2
Listing 4.2 Example of a SKILL.md file for a workspace analyzer skill
--- name: workspace-analyzer description: Inspect a workspace, identify temporary files, and perform only approved cleanup or organization steps. --- # Workspace Analyzer ## Instructions 1. Use `find` or the platform equivalent to locate temporary files such as `.tmp`, `.bak`, and editor backup files. 2. Run `git status --short` before making changes so tracked and untracked files are easy to distinguish. 3. Present the findings to the user and wait for confirmation before deleting or moving anything. 4. Delete only the approved files, then rerun the scan to verify the workspace is clean. 5. When reorganizing files, group them by extension into clearly named folders and report every move.
The workspace analyzer specifies a scan, approval, cleanup, and verification sequence. section 4.6.2
Instructions express intent; they do not enforce it. For destructive actions, the harness must enforce approval, and deletion should run in a sandboxed working directory. Before relying on a skill, test its triggering accuracy, completeness, safety, and performance on real tasks. File-based packaging also supports versioning and auditing. section 4.6.2 section 11.3.1 section 2.3





