agentleFS
Sign inStart free
LucSenaLucSena/how-to-build-software/AGENTS.md

how-to-build-software

AGENTS.md0 starsChanged 43 days agoMITView on GitHub

Guidance for AI agents (and humans) contributing to this repository. CLAUDE.md is a symlink to this file. A collection of Agent Skills (skills/<name>/SKILL.md) about software architecture, clean code, scalability, and 2026 web and mobile design. The skills are the product; everything else supports them. Conventional Commits: feat(skill-name): …, fix(skill-name): …, docs: …, chore: ….

The file

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

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

    Portable skills only: No agent-specific syntax ( !cmd , $ARGUMENTS, context: fork) inside SKILL.md.

    line 14
  2. Distinctive:

    Accuracy over completeness: Do not add figures, API names, or version numbers you cannot source.

    line 15
  3. Very specific:

    Check the router table in skills/how-to-build-software/SKILL.md — does an existing skill already cover it?

    line 28
  4. Very specific:

    Add the skill to the router's routing table and to related of the skills that should point to it.

    line 30

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

Guidance for AI agents (and humans) contributing to this repository. CLAUDE.md is a symlink to this file.

What this repo is

A collection of Agent Skills (skills/<name>/SKILL.md) about software architecture, clean code, scalability, and 2026 web and mobile design. The skills are the product; everything else supports them.

Rules

  1. Follow STYLE.md. It is the contract for frontmatter, required sections, reference files, voice, and evals.
  2. Keep skills flat. skills/<name>/ only. Categories go in metadata.category.
  3. Only spec keys at the top of frontmatter. Custom fields go under metadata as strings.
  4. Portable skills only. No agent-specific syntax (!`cmd`, $ARGUMENTS, context: fork) inside SKILL.md.
  5. Accuracy over completeness. Do not add figures, API names, or version numbers you cannot source. Label date-sensitive facts "as of YYYY-MM".
  6. Write in your own words. Ideas from permissive sources are fine with credit in CREDITS.md; do not copy text from sources with restrictive licenses.
  7. Bump versions. Any shipped change bumps the skill's metadata.version; releases bump VERSION and get a CHANGELOG.md entry.

Before committing

python3 scripts/validate_skills.py --strict   # must pass
python3 scripts/sync.py                        # regenerate README index + marketplace.json

Adding a skill

  1. Check the router table in skills/how-to-build-software/SKILL.md — does an existing skill already cover it? Prefer a new references/ file in an existing skill over a near-duplicate skill.
  2. Copy template/SKILL.template.md to skills/<name>/SKILL.md, then write it, references, and evals/evals.json.
  3. Add the skill to the router's routing table and to related of the skills that should point to it.
  4. Validate, sync, and add a CHANGELOG.md entry.

Commits

Conventional Commits: feat(skill-name): …, fix(skill-name): …, docs: …, chore: ….

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