imrohitagrawal

architecture-and-decisions

Create an architecture and decision walkthrough that explains how a software project fits together and WHY each significant choice was made, with the alternatives, the trade-offs, and the failure modes. Takes a reader from "can use it" to "understands it well enough to change or extend it safely." Produces Markdown (repo-first) with C4-style diagrams and a decision treatment for every important choice. Use this whenever the user wants an architecture doc, design doc, technical deep-dive, decision record narrative, "why is it built this way", or to understand the system in depth. Use it even if the user only says "document the architecture and the reasoning", "explain the design decisions", or "write the technical overview for a new engineer". For one technical reader who can already use the system — NOT a newcomer course (use learning-track), NOT operator recovery steps (use operations-runbook), NOT a look-up Q&A page (use project-faq).

doc-critic

Critically review the documentation a doc-suite skill produced — a learning track, architecture doc, runbook, FAQ, usage guide, or onboarding — before it is published, catching what a deterministic verifier cannot judge — cross-module contradictions, analogy and term collisions, code-vs-doc mismatches, undefined terms, simplifications that became false, honesty drift, and broken cross-references. It runs verify.py first, then a blind multi-axis agent critique (whole-document consistency, code-grounded correctness, the beginner floor, an adversarial adjudicator), writes a severity-ranked review register, and gates publishing on unresolved blockers. Use it after generating or editing docs, or to review, critique, QA, or harden the docs before publishing. It is the human-judgement layer on top of verify.py and an authoring skill's same-context critic loop, reviews the docs a skill produces rather than the skills themselves, and does not publish (use publish-mirror).

learning-track

Create a multi-audience learning track, course, or study companion teaching the concepts behind a software project using the project itself as the example. Produces modular, beginner-first Markdown lessons, repo-first, taking a reader from zero to understanding how it works and why. Use this whenever the user wants a learning track, course, curriculum, study guide, tutorial series, teaching material, lesson modules, or to turn a codebase into educational content. Use it even for requests like "help people learn how my project works" or "make study material from this codebase". Teaches concepts and the reasons behind them for newcomers (a tutorial, in Diataxis terms) — NOT step-by-step task instructions (use usage-guide), NOT a look-up reference (use project-faq), NOT contributor onboarding (use onboarding-companion), and NOT a deep design-and-decisions doc for engineers who already use it (use architecture-and-decisions).

onboarding-companion

Create a newcomer onboarding companion — a "buddy" guide plus a mentor voice — that takes a brand-new joiner, fresh graduate, or non-expert contributor from zero to productive on a software project. Covers setting up, running it end to end, reading the codebase in the right order, working day to day, getting unstuck, and the senior-engineer habits that matter when building with an AI coding agent. Produces Markdown (repo-first, an ONBOARDING.md plus a CONTRIBUTING section). Use this whenever the user wants onboarding docs, a contributor guide, a "getting started for new team members", a buddy guide, developer onboarding, or wants to help someone new start contributing. Use it even if the user only says "help new people get up to speed", "write a guide for new contributors", or "onboard a junior to this repo". This is for contributors, distinct from an end-user usage guide; it is not a multi-audience concepts course (use learning-track).

operations-runbook

Create operations runbooks and a troubleshooting guide for a software project — how to run it, how to monitor it, and exactly what to do when something breaks. Produces one action-first runbook per component (Markdown, repo-first) with a failure-mode entry per thing that can go wrong, plus monitoring signals, routine operations, and escalation. Use this whenever the user wants a runbook, ops guide, on-call doc, troubleshooting guide, incident playbook, SRE doc, "what to do when X fails", or wants to document how to operate, monitor, and recover their service. Use it even if the user only says "write the runbook for this", "document operations and on-call", or "how do we recover when it goes down". Built for projects that include AI components (model cost, drift, guardrails) as well as ordinary services. Operator-facing — not an end-user how-to (usage-guide), design rationale (architecture-and-decisions), or look-up Q&A (project-faq).

project-faq

Create a detailed, self-contained FAQ or question-and-answer wiki for a software project as a single tabbed HTML page with a grouped sidebar, deep links, and keyboard navigation. Every answer is multi-paragraph and carries two worked examples (one real from the project, one everyday analogy). Use this whenever the user wants an FAQ, Q&A page, knowledge base, help centre, project wiki, "common questions", or a page that answers "how does my project do X and why" for newcomers and teammates. Use it even if the user only says "make a page that answers questions about my project", "turn my notes into an FAQ", or "explain the decisions and the workflow for new joiners". Not a concepts course (learning-track), not the design-rationale doc (architecture-and-decisions), not a single-task how-to (usage-guide), not contributor onboarding (onboarding-companion). Includes a reusable Python generator so the HTML structure stays clean.

publish-mirror

Mirror repo-first documentation (Markdown or a finished HTML page) out to one or more published targets — a wiki such as Confluence, an educational portal — keeping the same visual language, accessibility, and built-versus-designed honesty. A separate publish step that runs AFTER an authoring skill has written and verified the source in the repository; it never authors content itself. Use this whenever the user wants to publish, mirror, sync, or push existing docs to Confluence, a wiki, or a learning portal, to set up repo-to-wiki publishing, or to add a publish destination. It reads a publish-targets manifest for every coordinate, renders through an adapter, records each change before editing a published page, gates every write behind human approval, and runs a publish-reviewer. NOT for writing the docs themselves (use learning-track, architecture-and-decisions, project-faq, usage-guide, operations-runbook, or onboarding-companion).

Web & Frontend Listed

usage-guide

Create a usage guide or how-to-use guide for a software project written so simply that even a young child at a grade-1 reading level can follow it. Short sentences, common words, one idea at a time, lots of concrete numbered steps, and pictures. Produces a clean illustrated single-file HTML page (or Markdown). Use this whenever the user wants a usage guide, how-to, user manual, getting-started guide, quickstart, step-by-step instructions, or the simplest-possible explanation of how to use their project. Use it even if the user only says "explain how to use this like I'm five", "write the simplest instructions", or "a guide my non-technical users can follow". Not a concepts course (learning-track), not a Q&A or knowledge base (project-faq), not the design-rationale doc (architecture-and-decisions), not contributor onboarding (onboarding-companion). Enforce the reading level with the bundled readability check.

watermark

Stamp the decorative credit watermark and a thin inset slate border onto an exported raster image (a diagram export, an OG/social-preview card) per render-contract.md's credit-furniture rule — placement is measured against the actual image (lowest-variance corner), never a fixed guess, and the script refuses rather than overlapping content it cannot confirm is empty. Use when an image LEAVES the project as a standalone file; never on the diagram source, and never as a substitute for the © licence footer, which HTML generators (project-faq, usage-guide) already render and shared/verify.py already hard-gates independent of this skill.

Testing & QA Listed

restated-mapping-fixture

A deliberately broken fixture skill whose publish step restates the render mapping that belongs only in render-contract.md. The render-restatement lint must catch it.