agentleFS
Sign inStart free
pproencapproenca/dot-skills/AGENTS.md

dot-skills

AGENTS.md201 starsChanged 7 months agoMITView on GitHub

dot-skills is a curated collection of Agent Skills (markdown rule packs + scripts). - skills/.curated/ — stable, published skills - skills/.experimental/ — new / in-progress skills. New skills start here. - Skills are authored and evolved with the dev-skill plugin: /dev-skill:new, :ingest, :evolve, :validate. - dev-skill disciplines: distillation / composition / investigation / extraction. Don't mix disciplines in one skill dir — adding a scripts/ dir to a distillation skill flips its detected discipline and breaks validation. Build a sibling…

  • 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 31,439 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 repository4 other files it gives its agents.

The file

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

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When asked to "run all the skill validation and audit scripts" (or before committing skill changes):

    line 14
  2. Distinctive:

    Always use TaskCreate for any task with 2+ steps

    line 27
  3. Distinctive:

    Never consider a skill done while the validator reports errors.

    line 44
  4. Very specific:

    When changing the tooling itself (scripts/, tests/), keep classic TDD: add/extend a fixture in tests/, watch it fail, then make npm test …

    line 45
  5. Distinctive:

    Make sure that the plan leads to comprensive list of tasks, dependencies defined where possible, it's better to slice tasks like carpaccio …

    line 51

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

What This Repo Is

dot-skills is a curated collection of Agent Skills (markdown rule packs + scripts).

  • skills/.curated/ — stable, published skills
  • skills/.experimental/ — new / in-progress skills. New skills start here.
  • Skills are authored and evolved with the dev-skill plugin: /dev-skill:new, :ingest, :evolve, :validate.
  • dev-skill disciplines: distillation / composition / investigation / extraction. Don't mix disciplines in one skill dir — adding a scripts/ dir to a distillation skill flips its detected discipline and breaks validation. Build a sibling skill instead.

Definition of Done — run before every commit

When asked to "run all the skill validation and audit scripts" (or before committing skill changes):

npm run validate                          # skills-ref: structural validation of every skill
node scripts/check-versions.mjs           # flag STALE/DIRTY skill versions
scripts/generate-readme-tables --update   # regenerate README skill tables
npm test                                   # skills-ref validator test suite

Fix every reported issue, then commit & push. A goal is not complete until verified.

Task Management

  • Always use TaskCreate for any task with 2+ steps
  • Break tasks into small, atomic units (carpaccio slicing)
  • Each task should be completable in a single focused action
  • Include acceptance criteria in task descriptions
  • Set up task dependencies with addBlockedBy/addBlocks

Development Workflow — Validator-First

Most work here is authoring markdown rule files, so the validators are the test gate (the equivalent of red-green-refactor):

  1. Red — run the validator and read the failures:
    • whole repo: npm run validate
    • single skill while authoring: dev-skill's discipline-aware validate-skill.js (/dev-skill:validate <path>)
  2. Green — fix rule files until the validator reports 0 errors.
  3. Refactor — tighten wording / dedupe rules, then re-validate to stay green.
  • Never consider a skill done while the validator reports errors.
  • When changing the tooling itself (scripts/, tests/), keep classic TDD: add/extend a fixture in tests/, watch it fail, then make npm test pass.

Plan Mode

  • At the end of each plan, give me a list of unresolved questions to answer, if any. Use the AskUserQuestions to clarify.
  • Make sure that the plan leads to comprensive list of tasks, dependencies defined where possible, it's better to slice tasks like carpaccio than overly broad tasks

Gotchas

  • Skill description ≤ 1024 chars (enforced by skills-ref). This is the most common validation failure — check length before committing a new or edited SKILL.md.
  • README tables are generated — always run scripts/generate-readme-tables --update; never hand-edit the skill tables in README.md (they get clobbered).
  • Per-skill validation during authoring uses dev-skill's validate-skill.js, which is separate from skills-ref and discipline-aware; aim for 0 errors.

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