skills
AGENTS.md6 starsChanged 20 days agoApache-2.0View on GitHub
This file defines how AI agents should work on this repository. It is not the primary skill installation guide. - For repository development, documentation edits, prompt edits, skill package edits, reviews, or commits, follow the repository work rules below. - Only when the user explicitly asks to install Skills from this catalog's published source, read INSTALL.md and follow that installation flow. - Do not switch into installation mode just because this repository contains skills/. - Use repo-map for separate repository…
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 32,671 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 repository23 other files it gives its agents.
- skills/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- api-specSkill
- ask-aiSkill
- dev-frontendSkill
- dev-javaSkill
- dev-rustSkill
- dev-testsSkill
- dev-typescriptSkill
- domain-modelingSkill
- human-writingSkill
- ops-browserSkill
- ops-clientSkill
- ops-deviceSkill
- product-specSkill
- repo-auditSkill
- repo-deliverySkill
- repo-mapSkill
- repo-reviewSkill
- to-taskSkill
- ui-specSkill
- work-retroSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
19 rules. About 0 are common, 5 are distinctive, and 14 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.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Only when the user explicitly asks to install Skills from this catalog's published source, read INSTALL.md and follow that installation …
- Very specific: line 9
Do not switch into installation mode just because this repository contains skills/.
- Very specific: line 10
Use repo-map for separate repository mapping, reuse inventory, or docs/code alignment.
- Very specific: line 11
Use api-spec for native API contract design, revision, and OpenAPI validation after business semantics are accepted.
- Very specific: line 12
Use domain-modeling when shared cross-functional business language or rules conflict.
- Very specific: line 15
Use dev-frontend, dev-typescript, dev-java, or dev-rust for requested code changes according to the actual owner.
- Very specific: line 16
Use repo-audit for bounded read-only frontend, Java, or Rust audits of existing surfaces without a change basis.
- Very specific: line 21
Use repo-review for read-only review of the current Worktree/index, a fixed immutable SHA/range, or a verified review package.
- Very specific: line 22
Use ask-ai for local external-AI packages or explicitly authorized review, research, visual exploration, and decision challenge with …
- Very specific: line 23
Use repo-delivery for categorized commits by default, explicit single commits, pushes, evidence-based branch integration, cleanup, and …
- Very specific: line 25
Use .codex/ as the local task workspace.
- Distinctive: line 36
Before modifying files, read this file plus directly related docs and code.
- Distinctive: line 37
Run git status --short before edits.
- Distinctive: line 38
Keep changes scoped to the requested task and preserve unrelated local changes.
- Distinctive: line 39
Use existing structure, tools, naming, and style.
- Distinctive: line 40
Run validation that matches the change, or state why it could not be run.
- Very specific: line 71
When editing or adding skill packages under skills/, also read skills/AGENTS.md, docs/skills/skill-standard.md, and …
- Very specific: line 72
When a provider format changes, update the standard, validator, focused tests, and docs/quality/official-skill-alignment.md together.
- Very specific: line 77
Use the validation matrix in skills/AGENTS.md.
≈ “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.
Files
Agent Instructions
This file defines how AI agents should work on this repository. It is not the primary skill installation guide.
Task Routing
- For repository development, documentation edits, prompt edits, skill package edits, reviews, or commits, follow the repository work rules below.
- Only when the user explicitly asks to install Skills from this catalog's published source, read
INSTALL.mdand follow that installation flow. - Do not switch into installation mode just because this repository contains
skills/. - Use
repo-mapfor separate repository mapping, reuse inventory, or docs/code alignment. - Use
api-specfor native API contract design, revision, and OpenAPI validation after business semantics are accepted; route implementation and fixed-change review to their existing owners. - Use
domain-modelingwhen shared cross-functional business language or rules conflict; load lifecycle or bounded-context depth only when that shared ambiguity requires it. Route feature-local behavior and acceptance toproduct-spec. - Use
to-taskwhen accepted Product/UI/architecture contracts or later findings need technical decomposition or reconciliation into a durable task ledger with dependencies, acceptance/evidence gates, status, blockers, and next action. It does not execute or schedule tasks. Use host planning for ephemeral reasoning that does not need a maintained task artifact. - For concrete failures, follow the effective personal or repository diagnosis rules before permanent remediation; use the matching implementation skill only when a source change is requested.
- Use
dev-frontend,dev-typescript,dev-java, ordev-rustfor requested code changes according to the actual owner. - Use
repo-auditfor bounded read-only frontend, Java, or Rust audits of existing surfaces without a change basis. Userepo-reviewfor a fixed Worktree or immutable change basis, including changes involving authentication, authorization, secrets, untrusted input, or other security risks; assess those risks as part of the ordinary Standards axis. - Use
repo-reviewfor read-only review of the current Worktree/index, a fixed immutable SHA/range, or a verified review package. Resolve pull requests to fixed base/head SHAs; apply Release only as a conditional profile over a fixed basis. - Use
ask-aifor local external-AI packages or explicitly authorized review, research, visual exploration, and decision challenge with ChatGPT, Gemini, DeepSeek, Kimi, or another named provider after the Codex-first gate; useops-browseronly for delegated low-level browser operations. - Use
repo-deliveryfor categorized commits by default, explicit single commits, pushes, evidence-based branch integration, cleanup, and other Git mutations.
Use .codex/ as the local task workspace. Store temporary files directly under one
category parent as .codex/<category>/<type>-<YYYYMMDD-HHmmss>.<ext> using local
time; use handoffs, reviews, artifacts, or tmp as the category and do not add
task, type, or date subdirectories by default. Related review files share one timestamped
prefix, such as .codex/reviews/ask-20260730-150931-package.md and
.codex/reviews/ask-20260730-150931-response.md. These category directories are
ignored. Put only explicitly approved, sanitized, durable handoffs or review evidence
under the repository's established docs/ structure.
Repository Work Rules
- Before modifying files, read this file plus directly related docs and code.
- Run
git status --shortbefore edits. - Keep changes scoped to the requested task and preserve unrelated local changes.
- Use existing structure, tools, naming, and style.
- Run validation that matches the change, or state why it could not be run.
- For add, reuse, move, rename, or delete work, keep source, package metadata, references, eval cases, root indexes, installation docs, and stale-name checks synchronized.
Project Structure
integrations/codex/owns reusable Codex-specific custom agent configurations. Edit these tracked sources before updating installed copies; follow its README for installation and byte-for-byte parity checks. Keep host-specific agents outside portableskills/packages and the Skill catalog indexes.skills/contains publishable or reusable skill packages.skills-index.jsonis the repository-level semantic discovery and execution- boundary contract used byscripts/search-skills.py; portable runtime activation remains inSKILL.md. Its mutation class is the maximum owned boundary, not proof that every invocation performs that effect.scripts/validate-skills.pychecks portable package structure, OpenAI metadata, local links, representative eval sections, semantic-index integrity, distribution hygiene, and catalog parity.scripts/run-skill-routing-evals.pyexecutes the catalog-wide normal, nearest- boundary, and critical-stop matrix. CI resolvesSKILLS_BASE_SHA(or the merge-base withorigin/main) to an immutable commit and reads the published baseline there; missing or invalid base authority and any published base without its baseline fail closed.scripts/report-skill-context.pyreports deterministic entrypoint and direct- reference context estimates as warnings; it does not claim exact model tokens or actual host loading behavior.scripts/sync-shared-protocols.pykeeps identical self-contained package protocols synchronized fromprotocols/.scripts/test_*.pycontains focused validator regressions.
When editing or adding skill packages under skills/, also read skills/AGENTS.md, docs/skills/skill-standard.md, and docs/standards/skill-routing.md.
When a provider format changes, update the standard, validator, focused tests, and
docs/quality/official-skill-alignment.md together.
Skill Validation
Use the validation matrix in skills/AGENTS.md. During iteration, run focused tests
for the changed validator, protocol, route, or package plus exact-path
git diff --check. Run the canonical full gate only for merge, release, catalog
delivery, final fixed-basis acceptance, or an explicit full-regression request.
For a behavior or quality claim, also run the fixed live-Agent cases required by
docs/skills/skill-standard.md, capture actual trace/artifacts, and report selection,
process, outcome/effect, stop honesty, and efficiency separately. Report any runtime
or external behavior that was not exercised; syntax, package, and deterministic
routing passes alone are not capability proof. Preserve any explicitly requested
independent provider/model in its live case; absent or mismatched provider evidence is
Not verified rather than an implicit exemption.
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
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.

