SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbootstrap-docs

bootstrap-docs

Writing & research

View repository

Updated 10-16 06:50

About this skill

Skill: Bootstrap project documentation

Purpose

Use project-documentation-template structure to guide or adjust project documentation. Two modes:Initialize(empty project — copy templates and fill placeholders) andAdjust(non-empty — use templates as a target, suggest renames/moves/merges, apply in place after confirmation). Supports repeatable runs; avoid empty directories and template files unless requested; enforce strict kebab-case. The output paths of products generated by the skill (ADR, backlog, design decisions, calibration) follow specs/artifact-contract.md; the project-documentation-template provides content and reference. When creating the process management structure, create for each contract docs/process-management/project-board/待办/ and docs/process-management/decisions/。

Core Objective

Governance objective: Through mode-appropriate bootstrapping or adjustment, generate structured lifecycle documentation consistent with enterprise templates.

Success criteria(all requirements must be met):

  1. ✅ Correct mode selection: Initialize for empty projects, adjust for non-empty projects (or apply user override)
  2. ✅ Apply template structure: Documentation follows the project-documentation-template conventions of the selected scale
  3. ✅ Placeholders filled: All [...] placeholders replaced with project-specific content (or explicitly marked for later use)
  4. ✅ Enforce naming conventions: All paths use strict kebab-case; ADR files follow the YYYYMMDD-slug-title.md format
  5. ✅ Obtain user confirmation: In adjust mode, apply changes only after the user approves the recommendation list

Repository test: Can developers navigate the documentation structure and find lifecycle documents without consulting the template repository?

Scope boundaries

This skill is responsible for：

  • Documentation structure bootstrapping (initialize mode)
  • Documentation structure adjustment (adjust mode)
  • Placeholder filling and validation
  • Path naming normalization (kebab-case)
  • ADR generation and indexing

This skill is not responsible for：

  • README generation (use "generate-standard-readme")
  • AGENTS.md entry creation (use generate-agent-entry）
  • Skill-specific documentation (use "refine-skill-design")
  • Content writing beyond template placeholders (domain content is provided by the user)

Handoff point: After the documentation structure is established and placeholders are filled, hand off to content authoring or project-specific documentation workflows.

Use cases

  • Empty project: Initialize a complete documentation framework by copying a template subset and filling placeholders for small/medium/large projects.
  • Non-empty project: Use templates as a target reference; analyze existing documentation, propose renames/moves/merges to adjust structure and naming; apply in-place changes after user confirmation. Do not create empty directories or template files unless requested. Can be run repeatedly.
  • Shared workflow: Generate Architecture Decision Records (ADRs), update version information across documents, validate placeholders and links.
  • Iterative runs: Repeatedly run the skill to progressively organize and refine the documentation; each run is based on the current state and does not require a complete re-initialization.

When to use: When a project needs structured lifecycle documentation consistent with enterprise templates, or when existing documentation should be made consistent with that structure.

Behavior (行为)

Stage 0: Norms Resolution (introduced in v2.0, simplified in v8.0)

Implemented per specs/artifact-contract.md §8 Runtime Norms Resolution Protocol . Applies to the ADR and other artifacts produced by this skill:

  1. Resolve project norms in the discovery order per §8.2 → determine the adrfor each artifact_type (especially path_pattern) (default:docs/process-management/decisions/YYYYMMDD-{slug}.md; projects may override to aggregate style)
  2. Substitute per the §8.3 placeholder syntax; for unresolved placeholders, ask the user per §8.6
  3. If the caller's frontmatter input contains upstream_ref(ADRs usually point to the associated design / requirement): in the frontmatter of the produced artifact, emit parent: <upstream_ref>
  4. Record resolved_path + frontmatter delta for use in subsequent writes

Note:initialization modethe project may not yet have ARTIFACT_NORMS.md, Stage 0 falls through to the skill default and does not block initialization work.

Mode selection

First determine the execution mode. User preference takes priority; otherwise:

Mode Trigger Behavior
Initialization No "docs/" or "docs/" is empty Copy the subset, fill in placeholders, create "VERSION", output the documentation skeleton
Adjustment docs/ has ≥1 valid document Scan, compare, output a recommendation list; apply after user confirmation

Detection rules：

  • No docs/ or docs/ is empty → Initialization
  • docs/ exists and has ≥1 valid .md file → Adjustment
  • The user explicitly specifies --mode=initialize or --mode=adjust → use that mode

Initialization mode steps

  1. Determine the project size: small, medium, or large (based on the user or context).
  2. Select a subset of documents from the templates by size:
    • Small: project overview, development guide, user guide
    • Medium: + architecture, design, requirements, and planning
    • Large: + process management, operations guide, compliance, community, and contribution
  3. Fetch templates from "TEMPLATE_BASE_URL" (see appendix) or use a local clone.
  4. Onlythe selected documents are copied into the project's "docs/". When the size allows, create contract-aligned directories based on specs/artifact-contract.md :docs/design-decisions/(medium+),docs/calibration/、docs/process-management/project-board/待办/、docs/process-management/decisions/(large). Optionally create "docs/ARTIFACT_NORMS.md" from the contract (per specs/artifact-norms-schema.md) for user customization. Do not create other empty directories unless the user explicitly requests it.
  5. Fill in placeholders with project metadata (name, date, tech stack), and prompt for missing key data.
  6. Create a "VERSION" file (e.g., "1.0.0") unless the user explicitly requests not to create a new file.
  7. Validation: no unreplaced placeholders, links valid, tables aligned.

Adjust Mode Steps

  1. Use project-documentation-template as the target reference for structure, conventions, and file/directory namestarget reference。
  2. Scan existing documentation under "docs/" (structure, placeholders, links, versions).
  3. Compare with the template and identify gaps:
    • Structure and path mismatches (non-standard directories/file names)
    • Documents can be aligned with the template (rename, move, or merge)
    • Unfilled placeholders, broken links, version inconsistencies
  4. Producerecommendation listand present it to the user; require confirmation before applying.
  5. After confirmation, apply the changesin placeto existing files. Do not create empty directories or add template files unless the user explicitly requests it. 6. This skill isidempotent: it can be run repeatedly to iteratively organize and refine documentation.

Conventions (from llms.txt)

  • Placeholders：[描述]、[选项1/选项2]、YYYY-MM-DD、[数字]
  • Tables: keep columns aligned; "*" marks required fields
  • Versions: use SemVer; update the version history at the bottom of the document for changes
  • References: internal[README](../../README.md); external[示例](https://example.com)
  • Dates：YYYY-MM-DD

File and directory naming (strict)

  • Directories: "kebab-case" only (e.g., "project-overview", "development-guide", "process-management")
  • Files: "kebab-case" with a ".md" extension (e.g., "goals-and-vision.md", "versioning-standards.md")
  • ADR files: each specs/artifact-contract.md docs/process-management/decisions/YYYYMMDD-slug.md
  • no spaces, underscores, or PascalCase; lowercase letters, numbers, and hyphens only.

Input & Output

Input

  • Project metadata: name, description, tech stack
  • Size: small|medium|large (optional; if absent, infer from context)
  • Mode override(optional):初始化 | 调整

Output

  • Initialize: indocs/、VERSIONpopulate the documentation below, along with a brief summary of the files created
  • Adjust: recommendation list (Markdown or structured), then - after confirmation - the applied changes and summary

Restrictions

Hard Boundaries

  • Replace all placeholders before finalizing the document; do not leave things like "[description]" in the final output unless explicitly deferred.
  • Do not add or keep broken internal links; validate relative paths.
  • Use consistent dates (YYYY-MM-DD) and SemVer for versions.
  • In adjust mode, do not apply changes without user confirmation.
  • Do not remove structural elements (sections, tables) from the template without user approval.
  • Do not create empty directories or add template files unless the user explicitly requests it.
  • When creating or renaming paths, use strict file and directory naming (kebab-case, ADR format "YYYYMMDD-title.md").

Skill Boundaries (Avoid Overlap)

Do not do these (other skills can handle them)：

  • README generation: Create or update the README.md file → use generate-standard-readme
  • AGENTS.md entry creation: Write or update the AGENTS.md file → use generate-agent-entry
  • Skill documentation: Create or optimize the SKILL.md file → use refine-skill-design
  • Content creation: Write domain-specific content beyond template placeholders → user provides content

When to stop and hand off：

  • The user says "the structure is ready" or "the placeholders are filled" → the document structure is complete, hand off to content creation
  • The user asks "How should I write the content?" → the structure is complete, hand off to a domain expert or content workflow
  • The user asks "Can you generate a README?" → hand off to "Generate Standard README"
  • The user asks "Can you create AGENTS.md?" → hand off to generate-agent-entry

Self-Check

Core success criteria (all criteria must be met)

  • Correctly select the mode: Initialize for an empty project, adjust for a non-empty project (or apply user overrides)
  • Apply the template structure: The document follows the project-document-template conventions of the selected scale
  • Placeholders are filled: All "[...]" placeholders are replaced with project-specific content (or explicitly marked for later use)
  • Enforce naming conventions: All paths use strict kebab-case; ADR files follow the YYYYMMDD-slug-title.md format
  • Obtain user confirmation: In adjustment mode, apply changes only after the user approves the recommendation list

Process quality checks

  • Links verified: Do internal links resolve and do external links point to valid resources?
  • Version consistency: Are the versions consistent between "VERSION" and the affected documents?
  • Table alignment: Is Markdown table alignment preserved?
  • No extra directories/files: Unless requested by the user, are empty directories and template files avoided?

Acceptance test

Can a developer browse the document structure and find lifecycle documents without consulting the template repository?

If no: the document structure is incomplete or unclear. Return to the mode-specific steps.

If yes: the document structure is complete. Proceed to handoff.

Examples (Examples)

Example 1: Initialization (empty project, small scale)

Context: A new repository "my-service" with no "docs/" directory.

Steps: The Agent selects Initialize; scale = small. Copy the project overview, development guide, and user guide from the template. Fill in the project name, date, and placeholder descriptions. Create "VERSION" as "1.0.0". Output a summary of the created files.

Output snippet：docs/project-overview/README.md、docs/development-guide/...、docs/user-guide/...、VERSION. All placeholders are filled with project-specific content.

Example 2: Adjustment (non-empty project)

Context: The repo has "docs/" and "project_overview/goals.md" (non-standard paths). Some placeholders are unfilled.

Steps: The agent chooses "Adjust". Using project-documentation-template as target. Produces a recommendation list:

  • Rename project_overview/ → project-overview/, directory index is README.md(kebab-case directory, README as entry point)
  • docs/project-overview/README.md Unfilled placeholders in:[项目描述]、[目标日期]
  • Broken links:../architecture/tech-stack.md(path does not exist)

The agent displays this list and asks: "Apply these changes? (yes/no)". The user confirms. The agent renames directories/files, fixes placeholders and links. No new empty directories or template files are created.

Example 3: Generic workflow — Generate an ADR

Context: Any project; the user needs an architecture decision record.

Steps: The agent obtains "docs/process-management/decisions/ADR-TEMPLATE.md" from the template. Determines the next ADR number (e.g., ADR-001). Fills in context, options, rationale, consequences with user input. Saves as "docs/process-management/decisions/YYYYMMDD-decision-title.md" (kebab-case slug) and updates the decision index (if present).

Appendix: Output contract

Initialization mode

Deliverable Required
"docs/" containing only the selected template files (no empty directories) Yes
版本 files Yes (unless the user explicitly requests not to add new files)
All placeholders replaced (or marked for later use) Yes
Version history table at the bottom of the document Every template

###Adjust Mode Recommendation List Format

Section Content
Target reference project-documentation-template
Path/naming issues Current path→recommended path (kebab-case, template-aligned)
Alignable documents Existing documents can be renamed/moved/merged to match the template
Unfilled placeholders File path + placeholder text
Broken/outdated links File path + link
Version issues Conflicting or missing version references

Template source

  • TEMPLATE_BASE_URL(canonical):https://raw.githubusercontent.com/nesnilnehc/project-documentation-template/main/
  • Key files:llms.txt、AGENTS.md、README.md、docs/
  • If retrieval fails (network unavailable): prompt the user to provide a local clone path or retry later; do not proceed with stale or missing templates.