DocSmith Documentation Generation

Generate and update structured documentation from workspace data sources. All outputs are created in the

.aigne/doc-smith/

workspace.

Constraints

The following constraints must be satisfied in all operations.

1. Workspace Constraints

The workspace must exist and be valid (config.yaml + sources) before any operation
The workspace has an independent git repository, and all git operations are performed under
```
.aigne/doc-smith/
```
If the workspace does not exist, initialize it following this process:
1. ```
mkdir -p .aigne/doc-smith/{intent,planning,docs,assets,cache}
```
2. ```
cd .aigne/doc-smith && git init
```
3. Create config.yaml (schema see below)
4. Initial commit

config.yaml schema：

yaml

workspaceVersion: "1.0"
createdAt: "2025-01-13T10:00:00Z"  # ISO 8601
projectName: "my-project"
projectDesc: "Project description"
locale: "zh"                        # Output language code, must confirm with user during initialization
projectLogo: ""
translateLanguages: []
sources:
  - type: local-path
    path: "../../"                  # Relative to workspace
    url: ""                         # Optional: git remote URL
    branch: ""                      # Optional: current branch
    commit: ""                      # Optional: current commit

Locale Confirmation Rule: When initializing the workspace, if the user does not explicitly specify the language, must use AskUserQuestion to confirm the output language (e.g., zh, en, ja), and must not write a default value.

2. Structure Constraints

```
document-structure.yaml
```
must comply with the schema below
After structure changes, must pass
```
/doc-smith-check --structure
```

After structure changes, must rebuild nav.js:

node skills/doc-smith-build/scripts/build.mjs --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist

document-structure.yaml schema：

yaml

project:
  title: "Project Name"
  description: "Project Overview"
documents:
  - title: "Document Title"
    description: "Brief Summary"
    path: "/filename"               # Must start with /
    sourcePaths: ["src/main.py"]    # Source file path (no workspace: prefix)
    icon: "lucide:book-open"        # Required only for top-level documents
    children:                       # Optional: nested documents
      - title: "Sub-document"
        description: "Detailed Information"
        path: "/section/nested"
        sourcePaths: ["src/utils.py"]

3. Content Constraints

Each document must have
```
docs/{path}/.meta.yaml
```
(kind: doc, source, default)
HTML must be generated in
```
dist/{lang}/docs/{path}.html
```
No
```
.md
```
files shall remain in the
```
docs/
```
directory (delete after build)
All internal links use the document path format (e.g.,
```
/overview/doc-gen
```
), build.mjs automatically converts to relative HTML paths
Resource references use the absolute path format
```
/assets/xxx
```
(build.mjs automatically converts to relative paths)

4. Human Confirmation Constraints

After inferring user intent, must confirm with the user (using AskUserQuestion)
After planning the document structure, must confirm with the user (using AskUserQuestion)
If there are changes after confirmation, re-confirmation is required

5. Context Management Constraints

The main agent can read project source files, but must reserve context space for subsequent Task results.

Judgment Principle: The amount of source files read by the main agent + the total summary volume returned by all subsequent Tasks must not exceed the context budget. The more documents there are, the more Task results there will be, and the smaller the space for the main agent to read source files itself.

Practical Rules:

When modifying a small number of existing documents, directly reading the relevant source files is acceptable
For initial generation: first evaluate the project scale through directory structure (
```
ls
```
/
```
Glob
```
), then decide the structure planning method:
- Small projects (few source files, expected documents ≤5): The main agent can directly read source files and plan the structure
- Large projects (many source files, expected documents >5): Delegate structure planning to a Task (see "Key Processes")

6. Task Distribution Constraints

Task Types:

Structure Planning Task (on-demand): When the project is large, delegate a Task to analyze source files and generate a draft of
```
document-structure.yaml
```
Content Generation Task: Distribute according to the prompt template in "Parallel Generation of Document Content", one Task per document

Distribution Rules:

Execute in parallel when the number of documents ≤5; batch execution when >5 (≤5 per batch), start the next batch only after the previous one is completed
Perform media resource scanning before content generation:
```
Glob: **/*.{png,jpg,jpeg,gif,svg,mp4,webp}
```
(exclude .aigne/ and node_modules/), pass the result as mediaFiles to each Task
All summaries returned by Tasks must be brief (≤10 lines), avoid returning file content

7. Completion Constraints

Pass
```
/doc-smith-check --structure
```
Pass
```
/doc-smith-check --content
```
The
```
dist/
```
directory contains HTML for all documents
```
nav.js
```
contains all document entries
Automatic git commit (under
```
.aigne/doc-smith/
```
directory)

Unified Entry

Scenario	Judgment Condition	Action
Initial Generation	`docs/` does not exist or user explicitly requests	Full process: Intent → Structure → Generation
Modify Existing Documents	`docs/` already exists	The AI understands the modification request, makes direct modifications, and only needs to satisfy the constraints

No changeset/PATCH mechanism is required for modification scenarios. Users describe modification requirements in natural language, and the AI executes them while satisfying constraints.

User Intent

File:

.aigne/doc-smith/intent/user-intent.md

Infer target users, usage scenarios, and document focus based on the project README and directory structure (

ls

Glob

). Confirm with AskUserQuestion after generation.

markdown

# User Intent

## Target Users
[Who are the main audiences]

## Usage Scenarios
- [Scenario 1]
- [Scenario 2]

## Document Focus
This document adopts the form of **[Document Type]**:
- [Focus 1]
- [Focus 2]

Structure Planning Principles

Planning must be based on user intent, only plan documents that are clearly needed
Flat structure is better than nested; choose a simpler structure when in doubt
Split conditions: 4+ chapters, independent content, no duplication, can be accessed independently
Do not split: thin content, sequential steps, duplication exists
After structure planning, confirm with the user using AskUserQuestion, showing the total number of documents, hierarchy, and the title and description of each document

Content Organization Principles

Navigation links can only link to generated documents (using path format), not to working directory files
Document opening: prerequisites, parent topic
Document ending: related topics, next steps, sub-documents
Overview documents with sub-documents: concise (150-300 words), 2-4 paragraphs per sub-topic + guiding links
Detailed documents without sub-documents: detailed (300-500 words), fully expanded

Key Processes

Structure Planning

After the main agent generates

user-intent.md

and confirms it with the user, select the structure planning method based on project scale:

Small Projects: The main agent directly reads source files, analyzes them, and generates
```
document-structure.yaml
```
Large Projects: Delegate a Task to analyze source files and generate a draft of
```
document-structure.yaml
```
, the Task returns the file path + structure summary (≤10 lines)

After generation, confirm with the user using AskUserQuestion, showing the total number of documents, hierarchy, and the title and description of each document.

Generate nav.js (After Structure Confirmation, Before Content Generation)

bash

node skills/doc-smith-build/scripts/build.mjs \
  --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist

Parallel Generation of Document Content

Each document is generated using a separate Task tool (≤5 in parallel, batch when >5). Must use the following template to construct the Task prompt, do not summarize the content of content.md on your own:

You are a documentation content generation agent. Please first use the Read tool to read {CONTENT_MD_PATH} as your complete workflow, then strictly follow the steps outlined in it.

Parameters:
- Document Path: {docPath}
- Workspace: {WORKSPACE_PATH}
- Linkable Documents List: {LINKABLE_DOCS}
- mediaFiles: {MEDIA_FILES}
- User Intent Summary: {INTENT_SUMMARY}

Key Tool Instructions:
- Use the Skill tool to call /doc-smith-images to generate images (Step 5.5)
- Use the Skill tool to call /doc-smith-check to validate documents (Step 7)

Completion Checklist (must confirm each item before returning the summary):
□ Step 5 Image Usage: Image references have been added to the document as needed
□ Step 5.5 Image Generation: All /assets/{key}/images/ references have been scanned and processed
□ Step 6.5 HTML Build: build.mjs --doc has been executed and HTML generation confirmed
□ Step 7 Validation: /doc-smith-check --content --path {docPath} has been called

Template Variable Explanation:

```
{CONTENT_MD_PATH}
```
: Absolute path of
```
references/content.md
```
```
{WORKSPACE_PATH}
```
: Absolute path of
```
.aigne/doc-smith
```
```
{docPath}
```
: Document path, e.g.,
```
/overview
```
```
{LINKABLE_DOCS}
```
: List of all document paths (extracted from document-structure.yaml)
```
{MEDIA_FILES}
```
: Media resource scanning results
```
{INTENT_SUMMARY}
```
: 2-3 sentence summary of user-intent.md

AI Inspection

After build completion, read the generated HTML files in

dist/

(spot-check 1-2 pages per language), check if the output meets expectations. If there are issues, directly modify the HTML files to fix them.

Automatic Commit