How to Create and Structure a New Agent Skill in mattpocock/skills

To create a new agent skill in mattpocock/skills, create a self-contained directory containing a 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 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; all other files exist for human readers or for deterministic scripts explicitly referenced by the skill.

A standard skill directory follows this layout:

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 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 (lines 37–58).

Step-by-Step Process to Create an Agent Skill

Following the process outlined in 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:

mkdir my-skill && cd my-skill

3. Write SKILL.md

Create the SKILL.md file using the template from 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 (lines 100–107):

• REFERENCE.md for extended documentation
• 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 (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:

npx skills@latest add mattpocock/skills/<skill-folder>

SKILL.md Template and Content Rules

The SKILL.md file serves as the single source of truth for the agent. According to the template in write-a-skill/SKILL.md (lines 37–58), the file must begin with front-matter:

---
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 (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.

Adding Optional Supporting Files and Scripts

While SKILL.md is mandatory, additional files improve maintainability for complex skills.

Supporting Documentation

• REFERENCE.md: Host detailed API documentation or advanced configuration options here when the skill is too large for a single file.
• 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:

#!/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.

Validating and Publishing Your Skill

Validation ensures the skill remains stable across codebase refactors. The Review Checklist in 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 under 100 lines unless split into 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:

npx skills@latest add mattpocock/skills/skill-name

As documented in the repository 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 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, EXAMPLES.md, scripts/) support progressive disclosure and deterministic automation.
• Validate all skills against the review checklist in 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/<skill-folder>.

Frequently Asked Questions

What is the minimum file structure required for a new skill?

The absolute minimum is a single 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, 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 (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 (lines 108–118). Once merged, users can add the skill to their projects by running npx skills@latest add mattpocock/skills/<skill-folder>, as documented in the repository README.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}