docs
Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit. Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs".
mthines · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mthines/agent-skills --skill docs技能说明
name: docs description: > Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit. Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs". argument-hint: '[init|update|readme|audit] [--auto|--dry-run] [--nested |--pattern ]' license: MIT metadata: author: mthines version: '1.0.0' workflow_type: command tags: - documentation - claude-md - readme - docs-folder - diataxis - drift-detection - tiered-docs - agent-readable - monorepo - placement-resolver - bootstrap - audit
Documentation
Author, audit, and maintain project documentation across every surface that matters: the agent hot path (CLAUDE.md, AGENTS.md, .claude/rules/), the human entry point (README.md), and the narrative tier (docs/).
This is the single home for "make our docs good" work — bootstrapping a new project, refreshing docs after a sprint, writing a README that converts readers into users, or auditing the whole estate for drift.
This
SKILL.mdis a thin index. Detailed authoring rules live inrules/*.mdand load on demand. Worked examples are inreferences/*.md. Literal scaffolding skeletons are intemplates/*.md. Do not preload everything — load only what the current phase asks for.
Mode Detection
Parse $ARGUMENTS (first token) and route to one of four modes.
A second token of --auto is a cross-cutting modifier (see below).
| Mode | Default | Trigger |
|---|---|---|
init | "init", "bootstrap", "scaffold", or $ARGUMENTS == "init" (no existing CLAUDE.md). | |
update | yes | Default when a CLAUDE.md already exists. "update", "sync", "refresh", "drift". |
readme | "readme", "write a README", "audit the README", or $ARGUMENTS == "readme". | |
audit | "audit", "review the docs", "doc health check", or $ARGUMENTS == "audit". |
--auto modifier — append to any mode token to enable the autonomous-workflow guardrails.
Always passed by autonomous-workflow Phase 5 as Skill("docs", "update --auto").
When --auto is present, also load auto-update-loop.md before executing the mode's phases.
Disambiguation rule when no mode token is passed:
- If
./CLAUDE.mddoes not exist →init. - Else if
./README.mddoes not exist and the user mentioned "README" →readme. - Else →
update.
State the detected mode in one line before continuing:
Mode: update
Target: this repo
Shared Foundations (every mode loads these)
Regardless of mode, every run is governed by three rule files. Load them once on first need; do not reload them per phase.
| File | What it gives you |
|---|---|
rules/content-routing.md | The Content Routing Rubric — which surface owns which kind of content, and why. |
rules/placement-resolver.md | The innermost-wins algorithm for picking the specific file (root vs nested CLAUDE.md, .claude/rules/ with paths:, etc.). |
rules/writing-style.md | Google + Microsoft style highlights, plain-language rules, and the agent-readable docs pattern. |
Then add the rule files specific to the mode:
| Mode | Additional rules to load |
|---|---|
init | claude-md.md, readme.md, docs-folder.md |
update | drift-detection.md, claude-md.md |
readme | readme.md |
audit | All of the above, plus maintenance.md for CI lint stack guidance. |
When invoked from a non-interactive caller (autonomous-workflow Phase 5) — passed as --auto — also load auto-update-loop.md.
That rule adds four non-negotiable gates (hot-path budget, recurrence threshold ≥ 2, removed-rules ledger, optional ablation) plus the JSON run-summary contract the caller logs.
Mode: init — bootstrap docs from scratch
Use when a project has no Claude configuration and (optionally) no documentation. Produces a tiered setup sized to the project's complexity.
Phases
- Detect existing config. Check for
CLAUDE.md,.claude/,AGENTS.md,README.md,docs/. If any exist, ask viaAskUserQuestion: Overwrite / Merge missing / Skip / Abort. - Triage complexity. Count source files, directories, monorepo
packages, CI/CD presence. See
references/archetypes.mdfor the small / medium / large thresholds and the per-tier file matrix. - Detect tech stack. Package manager (pnpm / npm / yarn / bun / poetry /
cargo / go.mod), test framework, linters, monorepo signal (
nx.json,turbo.json,pnpm-workspace.yaml). - Scaffold the tier's files. Use
templates/claude-md.md,templates/readme.md, and thedocs/*templates