skills
AGENTS.md0 starsChanged 52 days agoMITView on GitHub
This repo contains agent skills, grouped by category. CLAUDE.md imports this file, so edit rules here only. A new category needs a single lowercase word, a README section and an entry in the list above. Every SKILL.md starts with YAML frontmatter: Optional sections (place between Rules and Auto-Clarity Exception): - Mixing Ratio (for voice skills with intensity levels) - Multilingual Input (for skills handling non-English input) - When NOT to Use (explicit scope exclusions) Long material (templates, tables, worked examples)…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- skills/genai/photo-direction/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- photo-directionSkill
- shot-planningSkill
- manglish-modeSkill
- manglish-terseSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 0 are common, 9 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
After adding a skill, register it in .claude-plugin/plugin.json
- Distinctive: line 16
After adding a skill, add a section in README.md under the relevant category
- Distinctive: line 17
No em dashes anywhere in any file.
- Very specific: line 23
Every SKILL.md starts with YAML frontmatter:
- Distinctive: line 38
Persistence: - When the skill activates, when it deactivates, drift rules.
- Distinctive: line 40
Auto-Clarity Exception: - When to temporarily drop the skill (destructive ops, safety, confusion).
- Distinctive: line 42
Self-Check: - Test prompts and expected behavior for verification.
- Distinctive: line 47
When NOT to Use (explicit scope exclusions)
- Distinctive: line 52
Steps: - Start by working out which deliverable the user wants, then one step per deliverable.
- Distinctive: line 61
No em dashes anywhere
- Distinctive: line 62
No filler phrases ("it's worth noting", "at its core", "let me explain")
- Very specific: line 82
If a skill has dist/, it also needs a build script in scripts/.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
This repo contains agent skills, grouped by category. CLAUDE.md imports this file, so edit rules here only.
Categories
voice: changes how the agent talks (grammar, register, length). Adds no capability.genai: writes prompts for generative models and reviews what they produce (images, and later music or video).
A new category needs a single lowercase word, a README section and an entry in the list above.
Rules
- Each skill lives in
skills/<category>/<skill-name>/SKILL.md - After adding a skill, register it in
.claude-plugin/plugin.json - After adding a skill, add a section in README.md under the relevant category
- No em dashes anywhere in any file. The only exception is a skill rule or Not example that is about em dashes.
Skill Authoring Standard
Frontmatter (all skills)
Every SKILL.md starts with YAML frontmatter:
---
name: skill-name-here
description: One paragraph. Must include trigger phrases. Must explain what the skill does, not how.
---namerequired. Must match the folder name (kebab-case).descriptionrequired. Include all trigger phrases the user can say to activate the skill. Say what the skill is not for when a nearby request could trigger it by mistake.
Required sections: voice skills (in order)
- Opening line - One sentence that sets the tone. No heading.
- Persistence - When the skill activates, when it deactivates, drift rules.
- Rules - The core behavior. Subsections and examples live here.
- Auto-Clarity Exception - When to temporarily drop the skill (destructive ops, safety, confusion).
- Anti-Patterns - Not/Yes pairs showing common failure modes.
- Self-Check - Test prompts and expected behavior for verification.
Optional sections (place between Rules and Auto-Clarity Exception):
- Mixing Ratio (for voice skills with intensity levels)
- Multilingual Input (for skills handling non-English input)
- When NOT to Use (explicit scope exclusions)
Required sections: workflow skills (genai and other task skills, in order)
- Title and summary - What the skill produces and what it does not do.
- Steps - Start by working out which deliverable the user wants, then one step per deliverable.
- Output - The format of what the skill hands back.
- Gotchas - Real failures only, each tracing to something that happened. No preemptive gotchas.
- Reference files - Each file in
references/, with when to read it.
Long material (templates, tables, worked examples) goes in references/, not SKILL.md.
Voice rules for skill content
- No em dashes anywhere
- No filler phrases ("it's worth noting", "at its core", "let me explain")
- Lead with the rule, then explain if needed
- Examples must be generic (no real people's names, no company-specific references). Fictional character names are fine.
- Anti-patterns always show Not/Yes pairs
File structure
skills/<category>/<skill-name>/
├── SKILL.md (required)
├── README.md (optional, human-facing install and usage notes)
├── AGENTS.md (optional, pointer for AGENTS.md tools)
├── TESTING.md (optional, how to validate changes to the skill)
├── examples/ (optional)
├── references/ (optional)
├── scripts/ (optional)
├── agents/ (optional, per-tool metadata such as openai.yaml for Codex)
└── dist/ (optional, generated single-file build; never edit by hand)If a skill has dist/, it also needs a build script in scripts/. Run the script after every edit to SKILL.md or references/.
Naming
- Skill folders: kebab-case, no author prefix
- Category folders: single lowercase word
- Frontmatter
namematches folder name exactly
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

