infra-skills
AGENTS.md2 starsChanged 26 days agoMITView on GitHub
This repository is a set of agent instructions. When you are asked to change it, the most likely way to get it wrong is to edit the wrong copy of a file. skills/, .claude-plugin/, .codex-plugin/, .agents/plugins/ and the Pi fields of package.json are generated from .ai-rulez/. They are the obvious files to open — skills/infra-setup/SKILL.md looks like the skill — and editing them is silently undone by the next npm run generate. Before editing any file under those paths, check…
1 other project uses a version of this.
Adopted by
Most recently taken up by
- hasansezertasan/infra-copilotword for word, first seen Oct 18, 2026
Other versions1 project uses a version of this.
Word for word · 1
- hasansezertasan/infra-copilot★ 2100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
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,700 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 repository6 other files it gives its agents.
- infra-addSkill
- infra-importSkill
- infra-pruneSkill
- infra-setupSkill
- infraSkill
- infra-statusSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Before editing any file under those paths, check .ai-rulez-generated.json.
- Very specific: line 57
Never invoke npx ai-rulez, python3 scripts/validate.py, or the skills installer directly in documentation, in a commit's verification step, …
- Distinctive: line 89
No AI attribution in commits, PR titles, or bodies.
≈ “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.
Files
infra-skills — agent context
This repository is a set of agent instructions. When you are asked to change it, the most likely way to get it wrong is to edit the wrong copy of a file.
Rule 1: do not edit generated files
skills/, .claude-plugin/, .codex-plugin/, .agents/plugins/ and the
Pi fields of package.json are generated from
.ai-rulez/. They are the obvious files to open — skills/infra-setup/SKILL.md looks like the
skill — and editing them is silently undone by the next npm run generate.
Before editing any file under those paths, check .ai-rulez-generated.json. If the path
is listed (61 are), edit its source under .ai-rulez/ instead, then run npm run generate.
Most generated files carry an AI-RULEZ :: GENERATED FILE — DO NOT EDIT header, but
30 of the 61 do not — every non-Markdown output, because a Markdown comment is not
valid in them: the JSON manifests (marketplace.json, plugin.json),
config.md.example, decisions.md.example, steps.yaml, shell checks
(gcp-wif-trust.sh, gha-apply-gate.sh, gha-latest-runs.sh, hcp-apply-scope.sh,
hcp-bootstrap-workspaces.sh, hcp-github-app.sh, hcp-current-plan.sh, leaf-cloud.sh,
provider-requirements.sh, status-check-context.sh, gha-provider-safety.sh,
leaf-routing.sh, workflow-routing.sh, gha-workflows.sh, state-transfer.sh,
template-contract.sh), the pinned Copier requirements (copier-requirements.txt), App manifests
(templates/apps/terraform-plan.json, templates/apps/terraform-apply.json),
and the YAML workflow templates
(terraform-apply.yml, terraform-plan.yml), plus their CommonJS helper
(terraform-destroy.cjs). Absence of the header is not evidence a
file is safe to edit. The manifest is the authority; the header is only a convenience.
One writer is exempt: the release PR. release-please bumps the version in the three
generated JSON manifests alongside package.json, their version source, and the release
workflow then runs npm run generate on the PR branch and commits the result — the bump
changes the source hash every generated file records. That exemption covers only the
release workflow — hand edits to generated files are still wrong.
File resolution
| To change… | Edit | Then |
| A skill's behavior | .ai-rulez/skills/<name>/SKILL.md | npm run generate |
| Shared protocol, phase manifest, provider docs | .ai-rulez/skills/infra/references/… | npm run generate |
| A host's question tool or capabilities | .ai-rulez/skills/infra/references/hosts.md | npm run generate |
| A host's install instructions | docs/install-<host>.md | hand-authored — edit directly |
| Plugin identity, keywords | .ai-rulez/config.toml | npm run generate |
The plugin version or CHANGELOG.md | nothing — release-please's release PR bumps every copy | merge the release PR |
| What gets bumped at release | release-please-config.json | npm run check:all |
| Antigravity manifest | plugin.json | hand-authored — edit directly |
| Codex marketplace | .ai-rulez/config.toml ([plugin.codex]) | npm run generate — the file is generated |
| Repository validators | scripts/validate.py, tests/ | npm run check:all |
| The SessionStart hook | hooks/session-start.sh, hooks/hooks.json (Claude only) | hand-authored — ai-rulez has no hook support |
The infra-auditor subagent | agents/ (root, Claude dialect) | hand-authored — ai-rulez has no agent support |
| Tool pins | package.json + package-lock.json; versions only here, exact, and Renovate keeps them current | npm run check:all |
Rule 2: run npm run check:all
Never invoke npx ai-rulez, python3 scripts/validate.py, or the skills installer
directly in documentation, in a commit's verification step, or in the Linux CI job.
npm run check:all runs every check CI runs on Linux; CI also runs the Windows job below.
This governs this repository's own workflow. The install guides under docs/ address
a different audience: those commands run in the consuming repo, which has no copy of
these npm scripts, so they name each host's native installer — npx skills add on OpenCode,
/plugin install on Claude Code. That is the supported public install path and has been
the README's since #4. The rule binds maintainer instructions, not user instructions.
One deliberate exception: the windows-paths job in .github/workflows/check.yml calls
python scripts/validate.py and the tests directly, because the npm scripts
are not installed on windows-latest. That job exists to prove paths stay portable, not to be
CI parity. Leave
it as it is.
Architecture, in one paragraph
Five action skills — infra-setup, infra-import, infra-prune, infra-add, infra-status — are
thin routers over one hub
skill, infra-skills, whose references/ directory owns the behavior: steps.yaml (a
phase-tagged step manifest with a check per step), protocol.md (the actor model, the
handoff block, the resume scan, preflight), provider deep-dives, and runbooks. infra-setup
renders the paired Copier template, copier-infra (a separate repo; see ADR 0003), with the
Copier version pinned in references/copier-requirements.txt, and never hand-writes files that
Template owns. Host
packages are adapters and must never become a second behavioral authority. State is never
assumed: every run re-derives it by executing each step's check.
Conventions
- Conventional Branch names, Conventional Commits.
- No AI attribution in commits, PR titles, or bodies.
- Behavior in
.ai-rulez/skills/; host-specific values in adapters only. One declared exception:references/hosts.mdrecords what differs per host (native question tool and its capabilities, slash-command support) because the rules that read it are host-neutral and ship identically to all four hosts. The rule still binds what it was written for — a skill body must never name a host's tool; it reads the record instead. Change a capability there, not in an adapter.
See CONTRIBUTING.md for the full loop, which test covers which check
(#which-test-covers-a-check), and
docs/roadmap.md for what is deliberately unbuilt.
Agent skills
Issue tracker
Issues live as GitHub issues in hasansezertasan/infra-skills, driven with the gh CLI.
See docs/agents/issue-tracker.md.
Triage labels
The five canonical triage roles, each label string equal to its name. See
docs/agents/triage-labels.md.
Domain docs
Single-context: one GLOSSARY.md and docs/adr/ at the repo root, both created lazily.
See docs/agents/domain.md.
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.