SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdoc-smith-create

doc-smith-create

Writing & research

View repository

Updated 10-15 20:24

About this skill

DocSmith Document Generation

Generate and update structured documents from workspace data sources. All output is created in .aigne/doc-smith/ workspace.

Constraints

The following constraints must be satisfied in any operation.

1. Workspace Constraints

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

config.yaml schema：

workspaceVersion: "1.0"
createdAt: "2025-01-13T10:00:00Z"  # ISO 8601
projectName: "my-project"
projectDesc: "项目描述"
locale: "zh"                        # 输出语言代码，初始化时必须向用户确认
projectLogo: ""
translateLanguages: []
sources:
  - type: local-path
    path: "../../"                  # 相对于 workspace
    url: ""                         # 可选: git remote URL
    branch: ""                      # 可选: 当前分支
    commit: ""                      # 可选: 当前 commit

Locale Confirmation Rules: When initializing the workspace, if the user has not explicitly specified a language, AskUserQuestion must be used to confirm the output language (e.g., zh, en, ja); it must not be written by default.

2. Structure Constraints

  • document-structure.yaml Must conform to the schema below
  • After structural changes, it must pass /doc-smith-check --structure
  • After structural changes, nav.js must be rebuilt:node skills/doc-smith-build/scripts/build.mjs --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist

document-structure.yaml schema：

project:
  title: "项目名称"
  description: "项目概述"
documents:
  - title: "文档标题"
    description: "简要摘要"
    path: "/filename"               # 必须以 / 开头
    sourcePaths: ["src/main.py"]    # 源文件路径（无 workspace: 前缀）
    icon: "lucide:book-open"        # 仅顶层文档必需
    children:                       # 可选：嵌套文档
      - title: "子文档"
        description: "详细信息"
        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 the dist/{lang}/docs/{path}.html
  • docs/ directory; no .md files may remain (delete after build)
  • All internal links use the document path format (e.g., /overview/doc-gen), and build.mjs automatically converts them to relative HTML paths
  • Asset references use the /assets/xxx absolute path format (build.mjs automatically converts them to relative paths)

4. Human Confirmation Constraints

  • After user intent is inferred, it must be confirmed by the user (using AskUserQuestion)
  • After the document structure is planned, it must be confirmed by the user (using AskUserQuestion)
  • If there are changes after confirmation, they must be confirmed again

5. Context Management Constraints

Tasks use background execution mode (run_in_background: true), and execution logs do not flow back into the main agent context. The main agent obtains results through signal files (.status).

Practical Rules：

  • The main agent can freely read project source files and is no longer limited by the context budget of Task return values
  • On first generation, first assess the project scale through the directory structure (ls/Glob), then decide the structure planning method:
    • Small projects (few source files, estimated documents ≤ 5): the main agent can directly read source files and plan the structure
    • Large projects (many source files, estimated documents > 5): delegate structure planning to a Task (see "Key Processes")

6. Task Dispatch Constraints

Task types:

  • Structure Planning Task (as needed): when the project is large, delegate a Task to analyze source files and generate a document-structure.yaml draft
  • Content Generation Task: dispatch according to the prompt template in "Generate Document Content in Parallel", one Task per document

Dispatch rules:

  • All content generation Tasks must use run_in_background: true, to avoid execution logs flowing back into the main agent context
  • When the number of documents ≤ 5, execute in parallel; when > 5, batch them (each batch ≤ 5), and start the next batch only after the previous batch is complete
  • Before content generation, first perform a media asset scan:Glob: **/*.{png,jpg,jpeg,gif,svg,mp4,webp}(excluding .aigne/ and node_modules/), and pass the result as mediaFiles to each Task

Signal file mechanism:

  • When each Task completes, write the .aigne/doc-smith/cache/task-status/ file in {slug}.status file
  • slug rule: docPath with the / prefix removed, then use - to replace /(e.g. /api/overview → api-overview）
  • status file content is a 1-line summary (e.g. /overview: 成功 | HTML ✓ | .meta.yaml ✓）
  • main agent polls the .status file to determine whether a Task is complete (see "Batch Execution Flow")

7. Completion Constraints

  • /doc-smith-check --structure via
  • /doc-smith-check --content via
  • dist/ directory contains HTML for all documents
  • nav.js contains all document entries
  • automatic git commit (in the .aigne/doc-smith/ directory)

unified entry point

Scenario Condition Behavior
First-time generation docs/ does not exist or the user explicitly requests it full flow: intent → structure → generation
Modify existing documents docs/ already exists AI understands the modification request, modifies directly, and satisfies the constraints

Modification scenarios do not require a changeset/PATCH mechanism. The user describes the modification request in natural language, and the AI executes it and satisfies the constraints.

User intent

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

Infer the target users, usage scenarios, and documentation focus based on the project README and directory structure (ls/Glob). After generation, confirm with AskUserQuestion.

# 用户意图

## 目标用户
[主要受众是谁]

## 使用场景
- [场景 1]
- [场景 2]

## 文档侧重点
本文档采用**[文档类型]**的形式：
- [侧重点 1]
- [侧重点 2]

Structure Planning Principles

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

Content Organization Principles

  • Navigation links may only link to already generated documents (using the path format), not to files in the working directory
  • Document beginning: preconditions, parent topic
  • Document end: related topics, next steps, child documents
  • Overview documents with child documents: concise (150-300 lines), 2-4 paragraphs per subtopic + guiding links
  • Detailed documents without child documents: detailed (300-500 lines), fully expanded

Key Flows

Structure Planning

After the main agent generates user-intent.md and it is confirmed by the user, choose the structure planning method based on project scale:

  • Small project: the main agent directly reads the source files and, after analysis, generates document-structure.yaml
  • Large project: delegate a Task to analyze the source files and generate the document-structure.yaml draft; the Task returns the file path + structure summary (≤ 10 lines)

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

Generate nav.js (after structure confirmation, before content generation)

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

Image Backend Pre-detection

Before dispatching content generation Tasks, the main agent performs one image backend detection to determine the available backend. Background Tasks cannot interact with the user, so the detection must be completed in the foreground.

The detection logic is the same as the "Backend Detection" section of doc-smith-images :

  1. Check whether GEMINI_API_KEY is set → select gemini-sdk
  2. Otherwise, check whether the AFS CLI is available → selected afs-cli
  3. Neither is available → Must use AskUserQuestion to let the user choose(configure API Key / install AFS CLI / skip image generation), and automatically defaulting to skip is prohibited

Record the detection result as {IMAGE_BACKEND}(the value is gemini-sdk、afs-cli or skip), and pass it into the prompt template of each Task. It may be set to skip。

If {IMAGE_BACKEND} is gemini-sdk, you also need to ensure the dependencies are installed:

ls <skill-directory>/scripts/node_modules/@google/genai 2>/dev/null || (cd <skill-directory>/scripts && npm install)

Generate document content in parallel

Each document is generated using a separate Task tool (≤ 5 in parallel, > 5 in batches).Must use run_in_background: true to dispatch Tasks. The Task prompt must be constructed using the following template; the content.md content must not be summarized on your own:

你是文档内容生成代理。请先用 Read 工具读取 {CONTENT_MD_PATH} 作为你的完整工作流程，然后严格按照其中的步骤执行。

参数：
- 文档路径：{docPath}
- workspace：{WORKSPACE_PATH}
- 可链接文档列表：{LINKABLE_DOCS}
- mediaFiles：{MEDIA_FILES}
- 用户意图摘要：{INTENT_SUMMARY}
- 状态文件路径：{STATUS_FILE_PATH}
- 图片后端：{IMAGE_BACKEND}

关键工具说明：
- 使用 Skill 工具调用 /doc-smith-images 生成图片（步骤 5.5），必须传入 --backend {IMAGE_BACKEND}
- 使用 Skill 工具调用 /doc-smith-check 校验文档（步骤 7）

完成检查清单（必须在写入状态文件前逐项确认）：
□ 步骤 5 图片使用：文档中已按需添加图片引用
□ 步骤 5.5 图片生成：已扫描并处理所有 /assets/{key}/images/ 引用
□ 步骤 6.5 HTML 构建：已执行 build.mjs --doc 并确认 HTML 生成
□ 步骤 7 校验：已调用 /doc-smith-check --content --path {docPath}
□ 状态文件：已将 1 行摘要写入 {STATUS_FILE_PATH}

Template variable description：

  • {CONTENT_MD_PATH}：references/content.md absolute path
  • {WORKSPACE_PATH}：.aigne/doc-smith absolute path
  • {docPath}: document path, such as /overview
  • {LINKABLE_DOCS}: list of all document paths (extracted from document-structure.yaml)
  • {MEDIA_FILES}: media asset scan result
  • {INTENT_SUMMARY}: a 2-3 sentence summary of user-intent.md
  • {STATUS_FILE_PATH}：.aigne/doc-smith/cache/task-status/{slug}.status
  • {IMAGE_BACKEND}: image backend detection result (gemini-sdk、afs-cli or skip）

Batch execution flow

Preparation stage

Before dispatching the first Task:

  1. rm -rf .aigne/doc-smith/cache/task-status && mkdir -p .aigne/doc-smith/cache/task-status(rebuild the directory, clear the old state)

Dispatch stage

Each Task uses run_in_background: true to dispatch. All Tasks in a batch start at the same time.

Waiting stage

Check every 15 seconds .status number of files:

find .aigne/doc-smith/cache/task-status -name '*.status' | wc -l
  • Number of files = number of documents in the current batch → this batch is complete
  • Timeout: wait at most 10 minutes per batch; after timeout, report the missing documents
  • Do not read the output_file of a background Task(may be 300K+), only read .status file

Collect results

find .aigne/doc-smith/cache/task-status -name '*.status' -exec cat {} +

1 line per file; after all document summaries are aggregated, it is usually no more than 20 lines.

Failure handling

  • .status If the content starts with "failed" → record the failure reason without blocking subsequent batches
  • No output produced before timeout .status → mark as timed out, and prompt the user in the final report to retry

AI patrol inspection

After the build is complete, read dist/ the generated HTML files (spot-check 1-2 pages per language), and check whether the output matches expectations. If there are issues, directly modify the HTML files to fix them.

Auto commit

cd .aigne/doc-smith && git add . && git commit -m "docsmith: xxx"

Completion prompt

After all documents are generated and verified, show the generation summary to the user and prompt:

The documents have been generated. You can use /doc-smith-publish to publish the documents to an online preview.

Workspace directory structure

.aigne/doc-smith/
├── config.yaml
├── intent/user-intent.md
├── planning/document-structure.yaml
├── docs/{path}/.meta.yaml
├── dist/
│   ├── index.html
│   ├── {lang}/docs/{path}.html
│   └── assets/nav.js, docsmith.css, theme.css
├── assets/{key}/.meta.yaml, images/{lang}.png
├── glossary.yaml                  # 可选
└── cache/
    ├── translation-cache.yaml     # 发布用
    └── task-status/{slug}.status  # Task 完成信号文件