agentleFS
Sign inStart free
AryanRajMauryaAryanRajMaurya/shipfree/AGENTS.md

shipfree

AGENTS.md0 starsChanged 11 days agoMITView on GitHub

Repository guide for coding agents working on this repository. A single Agent Skill (shipfree) plus the harness that keeps its numbers true. The skill teaches an AI agent how to deploy an AI service on a free tier. The harness verifies every limit it quotes against the platform's own documentation. Never hand-edit a limit. The limit tables inside .agents/skills/shipfree/SKILL.md are generated. The source of truth is limits.json. To change a number: Editing the table directly is reverted by the next…

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

5 rules. About 0 are common, 1 is distinctive, and 4 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.

  • 4

    Very specific

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

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

    Every asserted limit needs a doc_label where upstream puts it in a table, so a renamed or removed limit is reported as drift instead of …

    line 62
  2. Distinctive:

    If you add a limit, add it in the same commit as the check that proves it.

    line 65
  3. Very specific:

    Do not add a number that is not verified against upstream.

    line 69
  4. Very specific:

    Do not copy the skill into a second location without updating tests/test_manifests.py, which asserts every copy is byte-identical.

    line 71
  5. Very specific:

    Do not claim a limit in the README that is not in limits.json.

    line 73

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

Repository guide for coding agents working on this repository.

What this repository is

A single Agent Skill (shipfree) plus the harness that keeps its numbers true. The skill teaches an AI agent how to deploy an AI service on a free tier. The harness verifies every limit it quotes against the platform's own documentation.

The one rule

Never hand-edit a limit.

The limit tables inside .agents/skills/shipfree/SKILL.md are generated. The source of truth is limits.json. To change a number:

python harness/fetch_limits.py --refresh   # pull the upstream docs
python harness/check_limits.py              # see what drifted
# edit limits.json with the new upstream value
python harness/render_skill.py              # regenerate the tables
python harness/render_skill.py --check      # confirm it is in sync

Editing the table directly is reverted by the next render and will fail CI.

Layout

.agents/skills/shipfree/SKILL.md   the canonical skill (source of truth)
.opencode/skills/shipfree/         copy for opencode; kept byte-identical
.cursor/rules/shipfree.mdc         always-on context for Cursor
.clinerules/, .kiro/steering/       always-on context for other harnesses
.github/copilot-instructions.md    always-on context for Copilot
.claude-plugin/, .codex-plugin/    plugin manifests per harness
.agents/plugins/marketplace.json   the agents-standard marketplace entry

limits.json                        the single source of truth for every limit
harness/fetch_limits.py            fetch upstream docs, parse limit tables
harness/check_limits.py            compare limits.json against upstream
harness/render_skill.py            regenerate the skill's tables from limits.json
templates/                         deployable starting points

Commands

make check        # everything CI runs
make limits       # refresh and check the limits
make render       # regenerate the skill tables
make test         # unit tests

Conventions

  • Python 3.10+, standard library only for the harness. No dependencies, so it runs anywhere and never needs a lockfile.
  • Conventional Commits for the commit subject, because the history is the advertisement.
  • Every asserted limit needs a doc_label where upstream puts it in a table, so a renamed or removed limit is reported as drift instead of passing silently.
  • If you add a limit, add it in the same commit as the check that proves it.

Do not

  • Do not add a number that is not verified against upstream. If it cannot be verified, it belongs in prose, not in limits.json.
  • Do not copy the skill into a second location without updating tests/test_manifests.py, which asserts every copy is byte-identical.
  • Do not claim a limit in the README that is not in limits.json.

Download now (ZIP)

  • 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 28,693 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 repository3 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

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