technical-docs
Writes technical documentation, specs and design docs (context, goals, ADR-style decisions, mermaid diagrams, rollout plan) and suggests where to store them. Use when asked to "document this", for a design doc, a spec, an ADR, a technical proposal or an architecture README.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- technical-docs
- metadata
- { "version": "1", "hub-owner": "shared" }
- description
- Writes technical documentation, specs and design docs (context, goals, ADR-style decisions, mermaid diagrams, rollout plan) and suggests where to store them. Use when asked to "document this", for a design doc, a spec, an ADR, a technical proposal or an architecture README.
03 SKILL.md 正文
Technical documentation
Before writing
hub_whoamifor the context andmemory_searchon the topic (previous decisions, existing docs, system names). Don't contradict a recorded decision without flagging it.- Read the real code you are documenting (models, endpoints, flows). Don't invent class, table or endpoint names:
if you haven't verified it, mark it
TODO: verify. - Pick the type: design doc/spec (something to build), ADR (one specific decision), system doc (how something that already exists works).
Design doc / spec structure
# Design: <title>
## Overview (3-5 lines: what and why)
## Goals / Non-goals (bullets; non-goals prevent scope creep)
## Current State (how it works today, with file paths)
## Problem Statement
## Proposed Architecture (+ mermaid diagram)
## Decisions (ADR format below, one per decision)
## Rollout / Migration (steps, feature flags, data migrations, rollback)
## Testing (unit, integration, e2e; what gets measured)
## Open Questions (with an owner if known)
Decisions (short ADR)
### D1: <decision in one line>
- Status: proposed | accepted | superseded by Dn
- Context: what forces the decision
- Options: A (pros/cons), B (pros/cons)
- Decision and consequences
Real pros and cons; if an option has no downsides, don't force a trade-off.
Diagrams
Use mermaid in a ```mermaid block: flowchart LR for pipelines and components, sequenceDiagram for
requests/webhooks/MCP, erDiagram for data models. At most ~15 nodes per diagram; split it if it grows.
Where to store it
- Follow the repo's convention if there is one (
docs/,design_docs/,adr/). Otherwise: design docs indocs/design/<topic>.md, ADRs indocs/adr/NNNN-<title>.md, system docs indocs/<TOPIC>.md, short ones inREADME.md. - Docs that must be visible outside the repo (wiki, task tracker) only if the user asks.
- Never paste secret values or
.envcontents; name the variable and say it lives in the secret manager (the hub injects it withsecret_http_request).
When done
- Check: would a newcomer understand the why without asking you? Is every claim about the code verified?
memory_savea self-contained note: date, doc path, main decision and status (proposed vs accepted). Passprojectwhere required.
04 同仓库更多 Skills
incident-postmortem
Writes a blameless incident postmortem (timeline, impact, root cause, contributing factors, action items) from logs, chat history or notes. Use after an outage, a failed deploy or a production bug, or when asked for an "incident report" or "postmortem".
release-notes
Writes user-facing release notes and a changelog entry from merged PRs or commits since the last release. Use when asked for "release notes", a "changelog" or "what changed since vX".
status-report
Builds a status report (weekly or for a period) by combining git history, the task tracker and hub memory; returns done / in progress / blockers / next steps. Use when asked for a status report, a weekly, "what did I do this week", a standup summary or an update for a manager.
review-pr
Reviews a pull request with a fixed checklist (correctness, security, tests, readability) and returns prioritized findings. Use when asked to review a PR, a diff or a code change.
memory-capture
Decides what is worth remembering from the conversation and saves it as short, self-contained notes with [[links]] to people, companies and projects. Use when the user says "remember this", "save this", "note that", or at the end of a session with decisions worth keeping.
meeting-notes
Turns a meeting transcript or rough notes into a summary with decisions, action items (owner + date) and open questions, and saves the durable parts to memory. Use when the user pastes a transcript, call notes or says "summarise this meeting".