Add skill
Skill1 starsChanged 8 days agoMITView on GitHub
Create a new reusable skill, either in the harness library or as a proposal from a generated project. Use when the user asks to add, create or extract a skill, or wants to turn a repeated workflow into instructions.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- Commit and pushSkill
- GitHub PagesSkill
- Logo designSkill
- Project setupSkill
- READMESkill
- Release cutSkill
- Release summarySkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Create a new skill that any agent can read and follow.
- Distinctive: line 21
Ask for, or infer from the conversation:
- Distinctive: line 24
when it should be used (the trigger).
- Distinctive: line 42
Write the body in English, in the imperative, with numbered steps.
- Very specific: line 43
Use plain git, gh and shell commands.
- Very specific: line 46
Keep it under roughly 150 lines.
- Distinctive: line 68
Use the same frontmatter and body, plus a short section explaining why the project needs it.
- Very specific: line 76
No absolute paths, no project-specific secrets, no references to the harness repository path.
- Very specific: line 84
Never write into .agent/.
- Distinctive: line 85
Never add a skill that duplicates an existing one.
- Distinctive: line 87
Never include credentials, tokens or user-specific paths.
- Very specific: line 88
Never change the locked decisions in setup/decisions.md through a skill.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
Add skill
Create a new skill that any agent can read and follow. Skills must stay self-contained and agent-agnostic.
1. Decide the scope
- Harness repository (the working tree contains
setup/decisions.mdandskills/): write the skill directly toskills/<id>/SKILL.md. - Generated project (
.agent/is a read-only submodule): write a proposal todocs/skill-proposals/<id>.mdand tell the user to apply it in the harness repository. Never write into.agent/.
2. Define the skill
Ask for, or infer from the conversation:
- the task it automates;
- when it should be used (the trigger);
- the exact steps and commands;
- what it must never do;
- whether it needs scripts or reference files.
3. Name and describe it
- ID: lowercase kebab-case, 1-64 characters, unique in
skills/. The directory name is the ID. - Frontmatter:
---
name: Short display name
description: One or two sentences covering what the skill does and when to use it. Include the words a user is likely to type.
---- Write the body in English, in the imperative, with numbered steps.
- Use plain
git,ghand shell commands. Do not depend on a specific agent's tools; when a decision is needed, say "ask the user" and optionally note that a dedicated question tool may be used. - Keep it under roughly 150 lines. Move long output samples to
references/. - Scripts go beside
SKILL.md, for exampleskills/<id>/scripts/run.mjs, and must be referenced by relative path.
4. Write it
Harness repository:
skills/<id>/SKILL.md
skills/<id>/scripts/... (optional)
skills/<id>/references/... (optional)Then add the skill to the index in skills/README.md.
Project proposal:
docs/skill-proposals/<id>.mdUse the same frontmatter and body, plus a short section explaining why the project needs it.
5. Validate
- The file is named exactly
SKILL.mdand lives inskills/<id>/. - The frontmatter has
nameanddescription. descriptionstates when to use the skill.- No absolute paths, no project-specific secrets, no references to the harness repository path.
- Commands are copy-pasteable and use placeholders such as
<id>. - The boundaries section exists when the skill performs git, release or file writes.
Boundaries
- Never write into
.agent/. - Never add a skill that duplicates an existing one; extend the existing skill instead.
- Never include credentials, tokens or user-specific paths.
- Never change the locked decisions in
setup/decisions.mdthrough a skill.
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.

