agentleFS
Sign inStart free
ianshankianshank/Agents/skills/AGENTS.md

Agents / skills

AGENTS.md1 starsChanged 58 days agoApache-2.0View on GitHub

A schema-validated marketplace of vendored skills. Registration is a CI gate, not a habit. Each skill is self-contained: its own SKILL.md contract, scripts, tests and evals. This directory owns registration and the CI tiering; a skill's own behaviour is owned by its SKILL.md. README.md is the human overview of what each skill does — read it for orientation, but treat marketplace.yaml as the authority. - A skill's contract file is SKILL.md, never README.md. That is the skill convention and it…

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Registration is fail-closed (ADR 0030): Every skills/<name>/ must appear in marketplace.yaml *and* must have either a dedicated job in …

    line 59
  2. Very specific:

    Keep README rows and versions aligned when you add or bump a skill, but never treat the table as the source of truth for registration or …

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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 — skills

A schema-validated marketplace of vendored skills. Registration is a CI gate, not a habit.

Each skill is self-contained: its own SKILL.md contract, scripts, tests and evals. This directory owns registration and the CI tiering; a skill's own behaviour is owned by its SKILL.md. README.md is the human overview of what each skill does — read it for orientation, but treat marketplace.yaml as the authority.

Map

PathRole
marketplace.yamlThe registry: name, version and path of every skill. Authoritative
marketplace.schema.jsonSchema marketplace.yaml is validated against
ci_exempt.yamlADR 0030 exemptions for skills with no library code. Single source
common/Shared validator library backing every vendored validate_skill.py. Not a skill
_generator_utils.pyShared helpers for the deterministic generator skills
<skill>/SKILL.mdThat skill's agent contract: preconditions, procedure, output, failures

Diagram

flowchart TD
  accTitle: what a new skill directory must satisfy
  accDescr: A new skill directory must be registered in marketplace.yaml and must have either a dedicated job in skills-ci.yml or an entry in ci_exempt.yaml, or the all-skills job fails the build.

  NEW["a new skill directory"]

  subgraph SK["skills/ (you are here)"]
    MKT["marketplace.yaml<br/>name + version"]
    SPEC["SKILL.md<br/>frontmatter version"]
    EX["ci_exempt.yaml"]
  end

  JOB["skills-ci.yml<br/>dedicated job<br/>coverage floor 95"]
  GUARD["all-skills job<br/>registration guard"]
  FAIL["build fails closed"]

  NEW --> MKT
  MKT --> SPEC
  NEW --> JOB
  NEW --> EX
  MKT --> GUARD
  JOB --> GUARD
  EX --> GUARD
  GUARD --> FAIL

  classDef here fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
  class SK here

Rules that bite here

  • A skill's contract file is SKILL.md, never README.md. That is the skill convention and it is deliberate. For the same reason no AGENTS.md may be added inside a skill directory: scripts/check_agents_md.py fails if one appears, because two instruction files beside each other invite disagreement. This file covers all of them.
  • Registration is fail-closed (ADR 0030). Every skills/<name>/ must appear in marketplace.yaml and must have either a dedicated job in .github/workflows/skills-ci.yml or a documented entry in ci_exempt.yaml. Missing either fails the all-skills job. A skill with library code carries a coverage floor of 95.
  • The semver in SKILL.md frontmatter must equal the one in marketplace.yaml. Bump both in the same commit or skill_marketplace.py validate fails.
  • README.md's skill table is hand-maintained; marketplace.yaml is authoritative. Keep README rows and versions aligned when you add or bump a skill, but never treat the table as the source of truth for registration or semver — read marketplace.yaml.
  • The research skills compose in one order. hierarchical-recursive-brainstorm expands a question into a pruned tree; openspec-quality-plan turns the strongest leaves into an OpenSpec package; openspec-peer-review critiques and rewrites it. Running them out of order produces a package with nothing behind its claims.

Verify

python scripts/skill_marketplace.py validate

Subagents

Task in this directoryAgentWhy
Find which skills declare a given helper or frontmatter fieldexplorerRead-only sweep over 19 directories; maxTurns: 5 covers one field
Run one skill's structural and behavioral validationtest-runnerHas Bash; validate_skill.py --tier structural,behavioral names the failing check
Review a new SKILL.md before registering itnarrow-criticContract gaps and unsafe shell in a procedure are not lintable

See also

DocRead it when
marketplace.yamlYou need a skill's real name, version or path — always prefer it over the README table
ci_exempt.yamlYour new skill ships no library code and CI is demanding a job for it
../docs/decisions/0030-skill-ci-tiers.mdYou are deciding which CI tier a skill belongs in, or why an exemption exists
../docs/SKILL_TEMPLATE.mdYou are scaffolding a new skill and need the SKILL.md shape
../scripts/AGENTS.mdYou edited the canonical validate_skill.py and the drift guard is failing

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.

Check your setup, free