agentleFS
idaibinidaibin/skills/skills/AGENTS.md

skills / skills

AGENTS.md6 starsChanged 20 days agoApache-2.0View on GitHub

skills/ contains the published packages. Before changing one, read ../docs/skills/skill-standard.md and the effective repository instructions. - Keep one public Skill per stable user intent and authority boundary. - Keep project task state in the target repository. to-task owns the reusable transformation and reconciliation workflow, not a catalog-side copy of any project's ledger. - Use profiles for framework or technology variants that share the same owner, workflow, mutation boundary, and output. - Keep SKILL.md as a concise entrypoint map using Entry…

The file

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

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep one public Skill per stable user intent and authority boundary.

    line 9
  2. Very specific:

    Keep project task state in the target repository.

    line 10
  3. Distinctive:

    Use profiles for framework or technology variants that share the same owner, workflow, mutation boundary, and output.

    line 11
  4. Very specific:

    Keep SKILL.md as a concise entrypoint map using Entry Gate, Route Map, Invariants, Output Map, and Reference Map.

    line 13
  5. Distinctive:

    Keep those five non-empty sections unique and in that order.

    line 17
  6. Very specific:

    Keep provider-specific metadata in its provider surface.

    line 22
  7. Very specific:

    Keep host orchestration, receipt/storage lifecycles, adapter names, and host schema namespaces outside portable packages.

    line 24
  8. Distinctive:

    Do not invent parallel per-provider files.

    line 26
  9. Distinctive:

    Do not put installation, update, changelog, or repository-maintenance guidance in published packages.

    line 28
  10. Very specific:

    When adding, renaming, or removing a package, update README.md, INSTALL.md, skills.sh.json, and skills-index.json in the same change.

    line 35
  11. Very specific:

    Use risk-tiered validation during development.

    line 42

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

Skills

skills/ contains the published packages. Before changing one, read ../docs/skills/skill-standard.md and the effective repository instructions.

Design Rules

  • Keep one public Skill per stable user intent and authority boundary.
  • Keep project task state in the target repository. to-task owns the reusable transformation and reconciliation workflow, not a catalog-side copy of any project's ledger.
  • Use profiles for framework or technology variants that share the same owner, workflow, mutation boundary, and output.
  • Keep SKILL.md as a concise entrypoint map using Entry Gate, Route Map, Invariants, Output Map, and Reference Map. Keep it at or below 8,000 Unicode characters; move route procedures, checklists, examples, and variants to directly linked one-level references loaded only for their named condition.
  • Keep those five non-empty sections unique and in that order. Only an optional non-empty Purpose H2 may precede them; local Markdown file and fragment links must resolve.
  • Packages must be self-contained. They may use their own scripts/, references/, and assets/, but must not depend on repository-root maintenance files at runtime.
  • Keep provider-specific metadata in its provider surface. This catalog includes agents/openai.yaml for OpenAI without treating it as portable frontmatter.
  • Keep host orchestration, receipt/storage lifecycles, adapter names, and host schema namespaces outside portable packages; Skills expose provider-neutral contracts.
  • Do not invent parallel per-provider files. Add another provider surface only when that provider documents a real machine-readable contract that this catalog ships.
  • Do not put installation, update, changelog, or repository-maintenance guidance in published packages.
  • Preserve unrelated changes and keep Git mutation in repo-delivery.

Shared package protocols are authored under protocols/ and synchronized with python3 scripts/sync-shared-protocols.py; do not hand-edit generated copies.

When adding, renaming, or removing a package, update README.md, INSTALL.md, skills.sh.json, and skills-index.json in the same change. When routing meaning, nearest neighbors, or capability keywords change, update the semantic index even when the package set stays the same.

Validation

Use risk-tiered validation during development. The canonical full gate remains bash scripts/check-skills.sh; on macOS it resolves and verifies Homebrew Python, refuses /usr/bin/python3, and uses uv with the pinned requirements-dev.txt when available. Other platforms use their configured PYTHON_BIN or python3.

For a bounded prose correction in one package, run exact-path whitespace/link checks and the smallest directly affected validator or regression. Do not run the full gate after every prose edit.

git diff --check -- skills/<name>

For a behavior, metadata, routing, schema, shared-protocol, or package-structure change, run the focused scripts/test_*.py cases and validators that cover the changed contract, plus shared-protocol sync checks when applicable. Expand to every affected consumer, but do not substitute an unrelated full suite for missing focused coverage.

For merge, release, catalog delivery, final fixed-basis acceptance, or an explicit full-regression request, run:

bash scripts/check-skills.sh

For behavior changes, keep the repository routing matrix synchronized with the affected Skill's normal use, nearest non-trigger or owner boundary, and critical stop. The full gate runs the deterministic routing matrix, its committed no-new-regression baseline, and a warning-only context report. Do not rerun it after an unchanged full pass unless the basis or relevant gate inputs changed. Real host/model behavior still requires representative live tasks when claimed. For a new or materially changed behavior, a real-failure repair, or an improvement claim, run the actual Agent on a fixed targeted prompt set and capture JSONL trace plus task artifacts. Cover explicit and implicit/contextual use, the nearest non-trigger, an applicable valid no-op, and the critical stop; score observable selection, process, outputs/effects, honest stop state, and efficiency separately. Keep public cases synthetic and project-neutral, keep raw business/project evidence ignored or private, and require human confirmation before replacing the maintained basis. Static gate counts cannot substitute for this live capability result. An explicitly requested independent provider/model remains a required live case dimension: absent or mismatched provider evidence is Not verified, not a waived pass. A formal cross-model benchmark remains optional.

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.