agentleFS
gabrielSantosLimagabrielSantosLima/harness/skills/add-skill/SKILL.md

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.

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
  1. Distinctive:

    Create a new skill that any agent can read and follow.

    line 8
  2. Distinctive:

    Ask for, or infer from the conversation:

    line 21
  3. Distinctive:

    when it should be used (the trigger).

    line 24
  4. Distinctive:

    Write the body in English, in the imperative, with numbered steps.

    line 42
  5. Very specific:

    Use plain git, gh and shell commands.

    line 43
  6. Very specific:

    Keep it under roughly 150 lines.

    line 46
  7. Distinctive:

    Use the same frontmatter and body, plus a short section explaining why the project needs it.

    line 68
  8. Very specific:

    No absolute paths, no project-specific secrets, no references to the harness repository path.

    line 76
  9. Very specific:

    Never write into .agent/.

    line 84
  10. Distinctive:

    Never add a skill that duplicates an existing one.

    line 85
  11. Distinctive:

    Never include credentials, tokens or user-specific paths.

    line 87
  12. Very specific:

    Never change the locked decisions in setup/decisions.md through a skill.

    line 88

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md and skills/): write the skill directly to skills/<id>/SKILL.md.
  • Generated project (.agent/ is a read-only submodule): write a proposal to docs/skill-proposals/<id>.md and 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, gh and 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 example skills/<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>.md

Use the same frontmatter and body, plus a short section explaining why the project needs it.

5. Validate

  • The file is named exactly SKILL.md and lives in skills/<id>/.
  • The frontmatter has name and description.
  • description states 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.md through a skill.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.