Skip to content

hoangminhung/devops-ai-kit / claude/skills/infra-docs

infra-docs

Verified

Write 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

TypeWhenAnswers the questionTemplateDefault location
Change recordEvery task at L1 or higherWhat changed, why, impact, risk, how to undo, prooftemplates/change-record.mddocs/changes/<task>/09-change-record.md
Concept noteA tool / stack that is new to the user or new in the projectHow it works, why it is designed this way, what happens when it breakstemplates/concept-note.mdthe personal KB folder if CLAUDE.md defines one, otherwise docs/concepts/
RunbookEvery component that is deployed / operatedHow to operate, debug, backup/restore, upgradetemplates/runbook.mddocs/runbooks/<component>.md
ADRA choice between options with long-term effectsWhy we chose thistemplates/adr.mddocs/adr/NNNN-<slug>.md
PostmortemAfter an incidentWhat happened, why, what we do so it does not happen againtemplates/postmortem.mddocs/postmortems/<YYYY-MM-DD>-<slug>.md

Read the matching template before you write, and keep its structure.

General rules

  1. 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.

  2. Write the version and the date. Infrastructure docs go out of date fast. Each doc has Applies to: <tool> <version> and Updated: <date>.

  3. 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.

  4. 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.

  5. Use Mermaid for diagrams so they render directly on GitHub/GitLab. Use a diagram when 3 or more components work together.

  6. 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.

  7. 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 with Supersedes: ADR-NNNN and change the old ADR's status to Superseded 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).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall