The Agent Skills format

A skill file that only works on your machine is not a skill — it is a personal note. The Agent Skills format is what makes a skill installable by anyone, indexable by a registry, and readable by any Claude instance without modification.

What this actually is

The Agent Skills format is a convention layered on top of the basic skill file structure from L3. The additions are minimal: a few extra frontmatter fields and a convention about where gotchas live. The goal is that a skill written by one person can be installed by another with a single command.

Here is the full format:

# scripts/deploy-gh-pages.md

---
name: deploy-gh-pages
description: Deploy a static site from the dist/ directory to GitHub Pages
author: Seth Shoultes
version: 1.2.0
dependencies: [run-tests, build-site]
triggers: [deploy, ship, publish to github pages]
license: MIT
---

## Prerequisites

- Node.js >= 18
- `gh-pages` npm package installed: `npm install --save-dev gh-pages`
- GitHub Pages enabled in repository settings (Settings > Pages > Source: gh-pages branch)

## Procedure

1. Confirm tests pass: run `npm test` — exit code must be 0
2. Build: `npm run build` — confirm `dist/` directory exists and is non-empty
3. Deploy: `npx gh-pages -d dist`
4. Verify: `curl -s -o /dev/null -w "%{http_code}" https://{{GITHUB_USERNAME}}.github.io/{{REPO_NAME}}/`
   should return `200`

## Gotchas

- **403 on deploy**: GitHub token may lack `repo` scope — re-authenticate with `gh auth login`
- **dist/ is empty**: The build step failed silently — check `npm run build` output for errors
- **404 on verify**: GitHub Pages propagation takes 1-2 minutes — wait and retry step 4

The new fields

dependencies tells the skill loader which other skills must be in context before this one executes. If run-tests fails, this skill should not start.

triggers is a list of natural language phrases that cause a skill loader to suggest this skill when the user types something similar. The skill registry uses these for search; Claude uses them for suggestion.

license matters when you publish. MIT is the default for open skills.

Prerequisites as a section

The prerequisites section is the place where you document what must be true in the environment before the procedure starts. This is distinct from dependencies (other skills) — prerequisites are environmental facts (tools installed, accounts configured, permissions granted). Without this section, the agent will attempt the procedure and fail at step one, which is the worst possible place to discover a missing requirement.

Why standardize

A common format means skills can be indexed, searched, and installed automatically. It also means that when someone else's skill breaks, the format gives you enough information to debug it: you know where to find the procedure, where to find the gotchas, and what the author intended the skill to do.

If you get stuck

If npx skills add cannot find your skill: the name field in the frontmatter must match the registry slug exactly. Hyphens, not underscores.

If a dependency skill is not available: the skill installer will report which dependency is missing. Install it separately first, then retry.

If you need to override a dependency (you have a custom version): copy the dependency skill locally and set dependencies: [] — then load both files manually.

Cross-reference

L8 (The install pattern) covers how the registry actually loads these files into Claude's context window, including how version pinning works.

Deliverable

Upgrade the skill file from L4 to the full Agent Skills format. Add the dependencies, triggers, and license fields. Add a prerequisites section. The success criterion: the frontmatter passes YAML validation and the prerequisites section lists everything a new environment would need before step one.

Further reading

• "Hooks Are Commitment Devices, Not Automations" — what a triggers field is doing structurally: not "auto-run this," but "commit to running this when these conditions hold."