agentleFS
Cody-SimsCody-Sims/agent-skills/AGENTS.md

agent-skills

AGENTS.md0 starsChanged 4 months agoMITView on GitHub

Instructions for agents working on this repository. This file governs changes to the catalog and its tooling. It is not a user guide; see README.md for install and usage. This repository is a portable Agent Skills catalog for Claude Code, GitHub Copilot, and OpenAI Codex. Its job is to hold high-quality, runtime-agnostic skills and the tooling that validates and installs them. Out of scope: - Runtime-specific behavior that cannot be expressed in the portable format. Do not add Claude-only or…

The file

We split this AGENTS.md 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:

    Do not add Claude-only or Cursor-only frontmatter to a canonical skill.

    line 23
  2. Very specific:

    Every skill is a directory under skills/ with exactly one SKILL.md:

    line 31
  3. Very specific:

    No other top-level keys are permitted.

    line 61
  4. Very specific:

    Keep SKILL.md under 500 lines and roughly 5,000 tokens.

    line 79
  5. Distinctive:

    Add a table of contents to any reference longer than 100 lines.

    line 84
  6. Distinctive:

    No emoji, no badges, no marketing language ("powerful", "seamless", "delightful").

    line 97
  7. Distinctive:

    Run these from the repository root and confirm they pass before completing any change to a skill or to the tooling:

    line 107
  8. Distinctive:

    Do not claim a change is complete without fresh output from these commands.

    line 121
  9. Distinctive:

    Write imperative commit subjects ("Add security-review skill", not "Added" or "Adds").

    line 128
  10. Very specific:

    Update CHANGELOG.md under Unreleased for every user-visible change.

    line 130
  11. Very specific:

    Never commit installed runtime copies (.claude/, .copilot/, .codex/) or *.receipt.json.

    line 131
  12. Distinctive:

    When the catalog changes, update the following in the same change:

    line 138

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

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

AGENTS.md

Instructions for agents working on this repository. This file governs changes to the catalog and its tooling. It is not a user guide; see README.md for install and usage.

Purpose and boundaries

This repository is a portable Agent Skills catalog for Claude Code, GitHub Copilot, and OpenAI Codex. Its job is to hold high-quality, runtime-agnostic skills and the tooling that validates and installs them.

In scope:

  • Skills under skills/<name>/.
  • Tooling under scripts/ and tests/.
  • The frontmatter contract in schemas/skill.schema.json.
  • Documentation under docs/ and the root Markdown files.

Out of scope:

  • Runtime-specific behavior that cannot be expressed in the portable format. Do not add Claude-only or Cursor-only frontmatter to a canonical skill.
  • Application code, product features, or repository-specific business logic inside a skill. Skills must stay repository-agnostic.
  • Hand-maintained per-runtime copies of a skill. Runtime copies are generated at install time.

Where skills live

Every skill is a directory under skills/ with exactly one SKILL.md:

skills/<name>/SKILL.md

<name> must be lowercase ASCII letters, digits, and single hyphens, and must equal the directory name. gh skill and the open standard require the skills/<name>/SKILL.md layout exactly; do not nest skills deeper, rename SKILL.md, or change its casing. Optional subdirectories are references/, scripts/, and assets/. Source: docs/research/anthropic-spec.md (section 2), docs/research/copilot-skills.md (section 3).

Frontmatter contract

SKILL.md frontmatter is YAML between two --- fences. The allowed keys are defined by schemas/skill.schema.json:

KeyRequiredTypeConstraints
nameYesstring1–64 chars; ^[a-z0-9]+(?:-[a-z0-9]+)*$; must equal the directory name; must not contain anthropic or claude.
descriptionYesstring40–1024 chars; third person; states what the skill does and when to use it; no < or >.
licenseNostringShort SPDX identifier or reference to a bundled license file.
compatibilityNostring1–500 chars; concrete environment, runtime, package, command, or network requirements. Omit when there are none.
metadataNomapString values only. metadata.version is a quoted semver string; metadata.tier is core, extended, or experimental.
allowed-toolsNostringExperimental and non-portable. Do not use in this repository.
user-invocableNobooleanCopilot VS Code and Claude Code extension.
disable-model-invocationNobooleanCopilot VS Code and Claude Code extension; use for destructive or expensive workflows.
argument-hintNostring1–200 chars; Copilot VS Code and Claude Code extension.

No other top-level keys are permitted. Claude-only fields such as when_to_use, model, effort, context, paths, and shell are rejected by the validator and break strict conformance. Put runtime-specific metadata in a companion file, not in the canonical frontmatter. Source: docs/research/anthropic-spec.md (sections 1, 8), docs/research/copilot-skills.md (section 5.3).

Progressive disclosure and size budgets

Skills use three loading levels. Keep each within budget.

LevelLoaded whenContentBudget
1: metadataAlways, at startupname, description~50–100 tokens per skill
2: SKILL.md bodyOn activationThe full instructions< 500 lines and < ~5,000 tokens
3: resourcesOn demandreferences/, scripts/, assets/No context cost until read or run

Rules:

  • Keep SKILL.md under 500 lines and roughly 5,000 tokens. Warn threshold is 400 lines / 4,000 tokens.
  • Move large, conditional, or domain-specific material into references/.
  • Link every reference directly from SKILL.md. Keep references one level deep; do not chain reference to reference.
  • Add a table of contents to any reference longer than 100 lines.
  • Ship a script only when the operation is deterministic, repetitive, fragile, or machine-verifiable. Prefer prose for judgment-heavy work.

Source: docs/research/anthropic-spec.md (section 3), docs/research/repo-tooling.md (section 4.1).

House writing style

  • Terse and factual. Short declarative sentences.
  • Numbered, procedural steps for workflows.
  • Third-person descriptions ("Reviews...", "Generates..."), never first or second person.
  • No emoji, no badges, no marketing language ("powerful", "seamless", "delightful").
  • Repository-agnostic wording. A skill must not assume a specific project, language, or directory unless stated in compatibility.
  • Descriptions must include concrete trigger vocabulary and an explicit "Use when..." clause. All activation information belongs in description, because the body is not loaded until after the skill is selected.

Required validation before finishing

Run these from the repository root and confirm they pass before completing any change to a skill or to the tooling:

npm run validate
npm test

For a portable-profile check that rejects every host extension:

node scripts/validate-skills.mjs --profile portable

Do not claim a change is complete without fresh output from these commands.

Git rules

  • Stage explicit paths: git add skills/<name>/SKILL.md. Never run git add -A or git add .; they capture scratch files, installed copies, and secrets.
  • Write imperative commit subjects ("Add security-review skill", not "Added" or "Adds").
  • Update CHANGELOG.md under Unreleased for every user-visible change.
  • Never commit installed runtime copies (.claude/, .copilot/, .codex/) or *.receipt.json; they are ignored by .gitignore.
  • Include the Co-authored-by: Copilot trailer on commits you create unless told otherwise.

Maintenance triggers

When the catalog changes, update the following in the same change:

ChangeUpdate
Skill addedREADME.md skills table; CHANGELOG.md (Added); add registry/discovery.json and registry/lifecycle.json metadata; regenerate the registry; run npm run validate and npm test.
Skill renamedDirectory name and name frontmatter together; every internal reference and link; discovery and lifecycle records; README.md skills table; CHANGELOG.md (Changed); regenerate the registry.
Skill removedDelete skills/<name>/ and its discovery record; move lifecycle metadata to a removed tombstone; README.md skills table; CHANGELOG.md (Removed); regenerate the registry.
Skill license, status, replacement, origin, or compatibility changesUpdate registry/lifecycle.json; record a real review event and annual due date where applicable; version an external upstream identity change; regenerate with --previous when comparing a base registry.
Frontmatter contract changedschemas/skill.schema.json; the frontmatter table above; docs/authoring-guide.md; docs/compatibility.md; every affected SKILL.md.
Tooling or npm script changedREADME.md command reference; package.json; docs/ as needed; add or update tests under tests/.

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.