mitodl/agent-kit/creating-skills

Creating a New Skill

Skills follow the Agent Skills open standard.

1. Choose a category

Place the skill under the most specific matching category in skills/:

If no category fits, create a new one and add a README.md for it.

2. Create the skill directory

The directory name becomes the skill's name. Use lowercase letters and hyphens only.

skills/<category>/<skill-name>/
└── SKILL.md

The name in SKILL.md frontmatter must exactly match the directory name.

3. Write SKILL.md

---
name: <skill-name>           # must match directory name; max 64 chars
description: >               # what it does AND when to use it; max 1024 chars
  <one or two sentences describing the skill and the keywords/scenarios
  that should trigger it>
license: BSD-3-Clause
metadata:
  category: <category>
---
 
# Skill Title
 
...instructions...

Description guidelines (most important field)

The description is what the agent uses to decide whether to activate the skill. Make it trigger-friendly:

• State both what the skill covers and when to use it.
• Include the specific tool names, command names, or scenario keywords an agent

would encounter when the skill is relevant.

• Bad: "Conventions for X." — too vague, won't trigger reliably.
• Good: "Apply X conventions. Use this skill when doing Y or Z — covers A, B, C."

4. Apply progressive disclosure

Keep SKILL.md under ~500 lines. If the skill has deep reference material (e.g., a detailed API reference, form templates, domain-specific lookup tables), move it to a references/ subdirectory and link to it from SKILL.md:

<skill-name>/
├── SKILL.md
└── references/
    └── REFERENCE.md

In SKILL.md, reference the file by relative path:

See [detailed reference](references/REFERENCE.md) for full option listings.

4b. Stay portable across agent platforms

Skills install on every platform agent-kit apply detects (Claude Code, Pi, Copilot, OpenCode), so don't make a Claude Code tool a hard requirement. When a step benefits from delegation, a structured question tool, or a built-in command, write it as a condition with a fallback in the same paragraph: "if a subagent facility is available, run one per batch in parallel; otherwise run the batches sequentially", "otherwise ask in chat". The fallback must do the same work, not a reduced version. Stock Pi has none of these tools; see Platform capabilities for the optional Pi extensions that add them. just check-skills flags a Claude-only mention with no fallback beside it.

4c. Never put body text on a command line

If the skill posts text to GitHub — an issue, a PR, a comment, a discussion, a review reply — write that text to a file and pass the path. Both halves matter:

• Use the file flag, not the string flag. gh takes --body-file; the

scripts in skills/process/ take --comment-file / --body-file, and - reads stdin. A body inlined as --body "..." has its backticks and $ expanded by the shell before the command runs, so a reply citing some_function posts with the identifier silently missing. Bodies routinely carry pasted errors, shell snippets, and backticked identifiers, so this is the common case rather than the edge one.

• Name the file with `mktemp`, never a fixed path. Several agents run the

same skill at once across different checkouts on one machine. A shared /tmp/<skill>-body.md means one of them publishes another's draft under its own title.

Writing a new script that posts text? Give it a file or stdin input from the start, and build any JSON payload with jq --arg / --rawfile rather than interpolating the text into the jq program.

5. Update the indexes

After creating the skill, update two places:

1. Category README (skills/<category>/README.md) — add a row to the table.
2. Top-level skills README (skills/README.md) — add a row to the All Skills table.

6. Validate

# Check frontmatter is valid (if skills-ref is available)
npx skills-ref validate ./skills/<category>/<skill-name>

If skills-ref is not installed, manually verify:

• name matches the directory name
• description is non-empty and under 1024 characters
• SKILL.md is the correct filename (uppercase)