菜单
Use when wiring the docs quality gate into CI/CD — turning docs-as-code:validate into a check that blocks pull requests on a docs/frontmatter/link failure. Covers GitHub Actions, GitLab CI, and a generic shell gate, plus making CODEOWNERS enforce doc review.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when applying Documentation-as-Code across many teams or a super-app / multi-repo / monorepo with several mini-apps — how to lay out per-team docs, own API contracts at boundaries, keep one traceability matrix across teams, and run the gate per changed area. The advanced (Lesson 6) counterpart to single-project docs-as-code.
Use when acting on an existing or in-progress Documentation-as-Code repo — assessing and scaffolding it, authoring or promoting a BRD/PRD/FR/NFR/ADR/Epic/Story/Test artifact, building a traceability matrix, versioning an inter-team API contract, validating frontmatter/links, auditing gaps and drift, or preparing a docs pull request. Routes the request to the right docs-as-code:* command. For a first-time conceptual introduction, defer to the docs-as-code-intro skill.
Use when measuring or reporting documentation health — explains the four docs-health metrics (coverage, freshness, contribution, contract-sync) that docs-as-code:audit reports, how each is computed, what target to hold, and how to read a declining one. For setting a docs SLO or a weekly health review.
Use when introducing a team to Documentation-as-Code — explains the principle, the minimum toolchain (Markdown + Git + PR review + CI), and the first three steps to adopt it on an existing project.
| name | docs-as-code-ci-setup |
| description | Use when wiring the docs quality gate into CI/CD — turning docs-as-code:validate into a check that blocks pull requests on a docs/frontmatter/link failure. Covers GitHub Actions, GitLab CI, and a generic shell gate, plus making CODEOWNERS enforce doc review. |
The point of docs-as-code is that the machine catches the mechanical errors (missing frontmatter, broken links, drift) so humans review judgement — but only if the check actually runs on every pull request and blocks merge when it fails. This skill wires that gate.
The primary gate is docs-validate.sh (frontmatter + Markdown lint + link check). It exits
non-zero on failure, so any CI system blocks the merge. Add docs-trace.sh --check (traceability
gaps) and check-contracts.sh (contract↔code) as additional required checks — a contract break
can hit a consumer who changed nothing of their own, so treat contract-sync as required, not optional.
The kit's own real, runnable workflow is
.github/workflows/validate.yml — note it is the kit's
self-test: it first runs validate-skills.sh (plugin manifest + skill linting), then applies the
docs gate (check-contracts.sh, docs-validate.sh, docs-trace.sh) scoped to
examples/nova-superapp. For a target repo you want only the docs steps, pointed at your docs
path — copy the trimmed, target-repo-ready workflow in
references/ci-examples.md, not the kit's self-test verbatim. Then set the job as a required status
check in branch protection so it truly blocks. (The bigger examples/nova-superapp/.github/ workflows/validate.yml is an illustrative super-app pipeline with placeholders — read it for the
multi-mini-app shape, but copy the real one above.)
For GitLab, add a job that runs bash scripts/docs-validate.sh in the test stage; a non-zero
exit fails the pipeline. For any other system, the rule is the same: run the one script, let its
exit code gate the merge. See references/ci-examples.md for copyable
GitHub Actions and GitLab snippets.
CI catches the mechanical; CODEOWNERS makes the human review mandatory. Add a CODEOWNERS that
routes docs/** to the doc owners and each contract to its consumers, then require code-owner
review in branch protection. Now a docs change cannot merge without both the green gate and the
right human sign-off.
Deployment of the check ≠ enforcement. A validate script that runs but does not block is theatre — the merge-blocking required-check is what stops drift.
