AgentSkillsCN

project-docs-generator

为任何软件项目（非特定领域）创建、扩展并验证“文档即代码”的文档体系。当被要求搭建完整的项目文档结构（docs/、specs/、epics/、prototypes/），撰写核心文档（章程、路线图、架构、模块/服务规格、运行手册，以及可选的合规性/可追溯性文档），添加交付计划（冲刺、UX/设计待办事项列表），并制定AI代理的实施指南（实施计划 + AGENT.md）时使用此功能。

SKILL.md
--- frontmatter
name: project-docs-generator
description: Create, expand, and validate a “docs-as-code” documentation set for any software project (not domain-specific). Use when asked to scaffold a full project documentation structure (docs/, specs/, epics/, prototypes/), write core documents (charter, roadmap, architecture, module/service specs, runbooks, optional compliance/traceability), add delivery planning (sprints, UX/design backlog), and create AI-agent implementation guidance (implementation plan + AGENT.md).

Project Docs Generator

Quick start (scaffold a docs set)

  1. •Decide your documentation scope (minimal vs standard vs regulated).
  2. •Scaffold a standard docs set:
    • •python3 <SKILL_DIR>/scripts/scaffold_project_docs.py --root . --project-name "My Project" --owner "Architecture + Product" --with-specs --with-epics --with-ops
  3. •If your project is regulated or needs audit readiness, include compliance scaffolding:
    • •python3 <SKILL_DIR>/scripts/scaffold_project_docs.py --root . --project-name "My Project" --owner "Architecture + Product" --with-specs --with-epics --with-ops --with-compliance
  4. •For full implementation-ready packs, generate the UX/design docs, sprint plan, and AI agent guidance described in Step 3.
  5. •Validate link hygiene:
    • •python3 <SKILL_DIR>/scripts/check_md_links.py --root .

Replace <SKILL_DIR> with the installed skill path (e.g., ~/.codex/skills/project-docs-generator).

Workflow (ask → research → write → validate)

Step 0) Clarify the goal and audience (ask first)

Ask the user the minimum questions from:

  • •references/questionnaire.md

Do not start writing “final” docs until you can answer at least:

  • •What are the critical user/business workflows?
  • •Is this a monolith or a distributed system (microservices/events)?
  • •What are the integration surfaces (APIs, events, files)?
  • •What are the non-functional targets (SLOs, throughput, RTO/RPO)?
  • •Is there any compliance/regulatory/audit requirement? If yes, which frameworks/sources are authoritative?
  • •What tech stack choices are locked (backend, frontend, mobile, data, IaC)?
  • •Do we need UI/UX planning artifacts (journeys, screen inventory, wireframes)?
  • •Do we need an AI agent implementation plan (AGENT.md + sprint execution plan)?

If details are missing, keep explicit TODO markers and add an “Open questions” section with owners.

Step 1) Pick a documentation blueprint (structure)

Use the default blueprint described in:

  • •references/docs-blueprint.md

Then scaffold with scripts/scaffold_project_docs.py.

Step 2) Research the right standards (don’t invent requirements)

When writing docs that cite standards, use authoritative sources and record them explicitly.

Use:

  • •references/research-sources.md

Rules:

  • •Prefer official specs (OpenAPI/AsyncAPI), RFCs, and established frameworks (C4, ADRs, OWASP, NIST/ISO).
  • •If compliance is in scope, create/maintain a sources register and traceability matrix (templates under assets/templates/standard/docs/06-compliance/).
  • •If unsure about an obligation, write it as a question with an owner; do not guess.

Step 3) Write docs in the right order (so it stays consistent)

Recommended sequence:

  1. •docs/DOCS_GOVERNANCE.md + docs/STYLE_GUIDE.md (sets the quality bar).
  2. •docs/00-project-charter.md + docs/00-vision-roadmap.md (why/what/when).
  3. •docs/02-architecture/* (system map, responsibilities, integrations, security, observability).
  4. •docs/03-modules/* (module/service specs that link to contracts).
  5. •specs/* (OpenAPI/AsyncAPI/file specs) and link them from the relevant module docs.
  6. •docs/01-discovery/* (journeys, screen inventory, UI/UX stories, wireframe checklist, design backlog).
  7. •epics/* (delivery backlog; stories with acceptance criteria + outputs).
  8. •epics/sprints/* (sprint plan, per-sprint backlogs, refinement).
  9. •docs/00-ai-agent-implementation-plan.md + AGENT.md (AI agent execution guidance).
  10. •docs/07-operations/* (runbooks, DR, incident response).
  11. •Optional: docs/06-compliance/* (requirements register, traceability, retention/legal hold).

Use the “quality bar” checklist in:

  • •references/quality-bar.md

Step 4) Validate and iterate (docs-as-code)

  • •Link hygiene:
    • •python3 <SKILL_DIR>/scripts/check_md_links.py --root .
  • •Contract hygiene (if applicable):
    • •follow the repo’s specs/QUALITY_GATES.md (or generate one via templates)
  • •Coverage checks (if UX/sprints are in scope):
    • •Every UX story appears in the sprint mapping.
    • •Every sprint backlog references its story files and acceptance criteria.

Bundled resources

  • •Templates: assets/templates/standard/ (docs/ + specs/ + epics/ + prototypes/)
  • •References:
    • •references/questionnaire.md (what to ask)
    • •references/docs-blueprint.md (what to generate)
    • •references/research-sources.md (what to cite)
    • •references/quality-bar.md (definition of done)
  • •Scripts:
    • •scripts/scaffold_project_docs.py (scaffold the docs set)
    • •scripts/check_md_links.py (validate repo-local Markdown links)