hoangminhung/devops-ai-kit / claude/skills/infra-docs
infra-docs
VerifiedWrite infrastructure documentation based on real evidence — change records of what was changed and why, concept/learning notes that explain how a tool or stack works, runbooks for operating a component, ADRs for architecture decisions, and blameless postmortems. Use whenever the user wants to document something, write handover or onboarding material, explain how a technology works for learning or for new team members, record a change, or write a runbook, ADR or postmortem.
Infrastructure documentation
Docs are for three readers:
- The user today, to understand what the AI just did and what the risks are.
- The same user in 6 months, when they need to operate, debug or upgrade.
- A new person, who needs to learn and take over.
Write so that all three can understand without asking again.
Choose the type of doc
| Type | When | Answers the question | Template | Default location |
|---|---|---|---|---|
| Change record | Every task at L1 or higher | What changed, why, impact, risk, how to undo, proof | templates/change-record.md | docs/changes/<task>/09-change-record.md |
| Concept note | A tool / stack that is new to the user or new in the project | How it works, why it is designed this way, what happens when it breaks | templates/concept-note.md | the personal KB folder if CLAUDE.md defines one, otherwise docs/concepts/ |
| Runbook | Every component that is deployed / operated | How to operate, debug, backup/restore, upgrade | templates/runbook.md | docs/runbooks/<component>.md |
| ADR | A choice between options with long-term effects | Why we chose this | templates/adr.md | docs/adr/NNNN-<slug>.md |
| Postmortem | After an incident | What happened, why, what we do so it does not happen again | templates/postmortem.md | docs/postmortems/<YYYY-MM-DD>-<slug>.md |
Read the matching template before you write, and keep its structure.
General rules
-
Mark where information comes from. Every important technical claim has one of three marks:
- ✅ checked with a command (with the command or short output, or a link to the task's log file);
- 📖 from the official docs (with the link and the docs version);
- ⚠️ guess / not checked.
This stops an AI guess from becoming wrong "knowledge" for the whole team after a few handovers.
-
Write the version and the date. Infrastructure docs go out of date fast. Each doc has
Applies to: <tool> <version>andUpdated: <date>. -
No secrets. No passwords, tokens, private keys, or connection strings with credentials. Point to where the secret is stored (Key Vault / secret name), not the value.
-
Commands must work. Commands in a runbook can be copied and pasted, use clear placeholders like
<namespace>, and say which context to run them in. Each mutating command has a warning right before it. -
Use Mermaid for diagrams so they render directly on GitHub/GitLab. Use a diagram when 3 or more components work together.
-
Write for someone who was not there. Explain each abbreviation the first time it appears. Do not write "as said above" without pointing to the section.
-
Language. Follow the output language rule (
01-language.md, set at install time with--lang). The project's CLAUDE.md can override it. Keep template headings as they are.
Concept notes (learning docs)
The goal is that the reader builds a correct mental model, not a copy of the official docs.
- Start with a comparison to something the reader already knows.
- Explain the data flow / control loop with a diagram.
- Point out what new people often get wrong, dangerous defaults, and how the system breaks.
- End with a few self-check questions for new people.
- Prefer examples from the user's own system (from recon / task logs) over generic examples. Mark them ✅ when checked on the real system.
ADRs
- Once an ADR is
Accepted, do not edit the decision. When the decision changes, write a new ADR withSupersedes: ADR-NNNNand change the old ADR's status toSuperseded by ADR-MMMM. - Do not put operating details in an ADR; link to the runbook.
- Number them in order: look at the highest file in
docs/adr/to get the next number.
Postmortems
- Blameless: describe the system and the decisions, do not blame a person.
- Include a "Lessons for the AI rules" section: which rule / skill in devops-ai-kit should be added or changed so the AI does not repeat the problem (if the AI was involved).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |