# How to Create and Structure a New Agent Skill in mattpocock/skills > Learn to create and structure a new agent skill in mattpocock/skills. Follow our guide for directories, SKILL.md files, documentation, scripts, and validation for seamless integration. - Repository: [Matt Pocock/skills](https://github.com/mattpocock/skills) - Tags: tutorial - Published: 2026-04-04 --- **To create a new agent skill in mattpocock/skills, create a self-contained directory containing a [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file with specific front-matter metadata, optionally add supporting documentation and deterministic scripts, and validate your work against the review checklist before publishing.** The **mattpocock/skills** repository provides a framework for agent-discoverable capabilities, where each skill follows a strict convention to ensure automatic discovery and execution. When you create and structure a new agent skill, you must adhere to a specific directory layout and metadata format defined in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) so the skills CLI can parse and invoke your skill without additional configuration. ## Required File Structure for a New Agent Skill Every skill is a shallow, self-contained directory that the agent can add to a project via the CLI. The **only** file the agent reads automatically is [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md); all other files exist for human readers or for deterministic scripts explicitly referenced by the skill. A standard skill directory follows this layout: ```text skill-name/ ├── SKILL.md # Required – entry point with front-matter metadata ├── REFERENCE.md # Optional – detailed documentation for complex skills ├── EXAMPLES.md # Optional – concrete usage snippets └── scripts/ # Optional – deterministic helper scripts └── helper.js ``` The [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file must contain YAML front-matter with `name` and `description` fields, which the CLI parses at load time to determine when the skill should be invoked. Keeping the directory shallow (no nested sub-folders beyond `scripts/`) ensures the skill remains easy to version, publish, and discover according to the canonical template in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 37–58). ## Step-by-Step Process to Create an Agent Skill Following the process outlined in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 10–15), here is the complete workflow for creating a skill: ### 1. Gather Requirements Ask the user what the skill should accomplish, identify required inputs, and determine if any deterministic scripts need to be bundled to save token budget and increase reliability. ### 2. Create the Directory Initialize a new folder for your skill. Use a descriptive, kebab-case name: ```bash mkdir my-skill && cd my-skill ``` ### 3. Write SKILL.md Create the [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file using the template from [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 37–58). The front-matter must include a `name` and a `description` that follows four strict rules: - Must be ≤ 1024 characters - Must be written in third-person - Must start with a one-sentence capability statement - Must end with "Use when …" The body should include a **Quick start** example and a **Workflows** section describing the execution steps. ### 4. Add Optional Supporting Files If the skill is large, split content across additional files as recommended in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 100–107): - **[`REFERENCE.md`](https://github.com/mattpocock/skills/blob/main/REFERENCE.md)** for extended documentation - **[`EXAMPLES.md`](https://github.com/mattpocock/skills/blob/main/EXAMPLES.md)** for additional usage scenarios - **`scripts/`** for deterministic helper scripts (e.g., Bash or Node.js utilities) ### 5. Validate Against the Review Checklist Before publishing, run through the **Review Checklist** at the end of [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 108–118). Ensure the description includes clear triggers, the file is under 100 lines (unless split), contains no time-sensitive information (hard-coded paths or line numbers), and follows the third-person convention. ### 6. Publish Once validated, the skill can be added to another repository via the CLI: ```bash npx skills@latest add mattpocock/skills/ ``` ## SKILL.md Template and Content Rules The [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file serves as the single source of truth for the agent. According to the template in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 37–58), the file must begin with front-matter: ```markdown --- name: my-skill description: Generates a UUID v4 string. Use when a unique identifier is needed. --- ``` The description pattern shown above follows the required format detailed in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 70–75): a capability statement followed by a "Use when …" trigger clause. The body content should practice **progressive disclosure**, keeping the core capability concise and pushing large explanations to [`REFERENCE.md`](https://github.com/mattpocock/skills/blob/main/REFERENCE.md). ## Adding Optional Supporting Files and Scripts While [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) is mandatory, additional files improve maintainability for complex skills. ### Supporting Documentation - **[`REFERENCE.md`](https://github.com/mattpocock/skills/blob/main/REFERENCE.md)**: Host detailed API documentation or advanced configuration options here when the skill is too large for a single file. - **[`EXAMPLES.md`](https://github.com/mattpocock/skills/blob/main/EXAMPLES.md)**: Provide concrete, copy-paste-ready snippets that demonstrate various usage scenarios. ### Deterministic Scripts Place helper scripts in the `scripts/` directory. These must perform pure, repeatable operations (validation, formatting, extraction) to maintain reliability. For example: ```bash #!/usr/bin/env bash # scripts/extract.sh pdf_file=$1 pdftotext "$pdf_file" - | jq -R -s '.' ``` The skill explicitly calls these scripts during its workflow, but the agent never executes them automatically unless referenced in [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md). ## Validating and Publishing Your Skill Validation ensures the skill remains stable across codebase refactors. The **Review Checklist** in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 108–118) mandates: - **No time-sensitive content**: Avoid hard-coded file paths or line numbers that might change. - **Length constraints**: Keep [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) under 100 lines unless split into [`REFERENCE.md`](https://github.com/mattpocock/skills/blob/main/REFERENCE.md). - **Description quality**: Verify the description includes clear triggers and stays within the 1024-character limit. After validation, publish by pushing to the repository. Users can then install your skill using: ```bash npx skills@latest add mattpocock/skills/skill-name ``` As documented in the repository [`README.md`](https://github.com/mattpocock/skills/blob/main/README.md), this command pulls the skill directory and integrates it into the target project. ## Summary - A new agent skill requires a directory containing at minimum a [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file with valid front-matter (`name` and `description`). - The `description` must follow strict formatting rules: ≤1024 characters, third-person, capability statement, and "Use when …" trigger. - Optional files ([`REFERENCE.md`](https://github.com/mattpocock/skills/blob/main/REFERENCE.md), [`EXAMPLES.md`](https://github.com/mattpocock/skills/blob/main/EXAMPLES.md), `scripts/`) support progressive disclosure and deterministic automation. - Validate all skills against the review checklist in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 108–118) to ensure no time-sensitive data and proper line limits. - Publish by making the skill available in the repository, allowing installation via `npx skills@latest add mattpocock/skills/`. ## Frequently Asked Questions ### What is the minimum file structure required for a new skill? The absolute minimum is a single [`SKILL.md`](https://github.com/mattpocock/skills/blob/main/SKILL.md) file inside a directory named after the skill. This file must include YAML front-matter with `name` and `description` fields so the CLI can discover and invoke the skill. All other files ([`REFERENCE.md`](https://github.com/mattpocock/skills/blob/main/REFERENCE.md), [`EXAMPLES.md`](https://github.com/mattpocock/skills/blob/main/EXAMPLES.md), `scripts/`) are optional and only needed for complex capabilities. ### What are the specific rules for writing the skill description? According to [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 70–75), the description must be four things: (1) no longer than 1024 characters, (2) written in third-person, (3) starting with a one-sentence capability statement, and (4) ending with a "Use when …" clause that triggers the agent to select the skill. ### Can I include helper scripts in my skill? Yes, you can include deterministic helper scripts inside a `scripts/` directory. These scripts should perform pure, repeatable operations (such as data validation or file parsing) to save token budget and increase reliability. The skill invokes them explicitly during its workflow, but they are never executed automatically by the agent framework. ### How do I publish a skill to the mattpocock/skills repository? Publishing involves submitting your skill directory to the repository (typically via pull request) and ensuring it passes the review checklist in [`write-a-skill/SKILL.md`](https://github.com/mattpocock/skills/blob/main/write-a-skill/SKILL.md) (lines 108–118). Once merged, users can add the skill to their projects by running `npx skills@latest add mattpocock/skills/`, as documented in the repository [`README.md`](https://github.com/mattpocock/skills/blob/main/README.md).