文件產生器技能

文件產生器技能

Language: English | 繁體中文

版本: 1.0.0 最後更新: 2026-01-26 適用範圍: Claude Code Skills

---

用途

自動從專案來源檔案產生完整的使用說明文件。此技能會建立：

1. FEATURE-REFERENCE.md：包含所有細節的完整功能文件
2. CHEATSHEET.md：單頁速查表

支援多語言（英文、繁體中文、簡體中文），並掃描各種來源：

• CLI 指令
• 斜線命令
• 技能
• 代理
• 工作流程
• 核心規範
• 腳本

快速參考

產生所有文件

node scripts/​generate-usage-docs.mjs

產生特定語言

node scripts/​generate-usage-docs.mjs --lang=en       # 僅英文
node scripts/​generate-usage-docs.mjs --lang=zh-TW    # 繁體中文
node scripts/​generate-usage-docs.mjs --lang=zh-CN    # 簡體中文

產生特定格式

node scripts/​generate-usage-docs.mjs --cheatsheet    # 僅速查表
node scripts/​generate-usage-docs.mjs --reference     # 僅參考手冊

檢查同步狀態

# 檢查文件是否需要更新
node scripts/​generate-usage-docs.mjs --check

# 或使用同步檢查腳本
./​scripts/​check-usage-docs-sync.sh         # 檢查
./​scripts/​check-usage-docs-sync.sh --fix   # 需要時修復

配置

產生器使用專案根目錄的 .usage-docs.yaml 來定義：

• 輸出路徑：文件產生位置
• 語言：要產生的語言版本
• 來源：要掃描的內容（CLI、技能、命令等）
• 範本：文件結構範本

配置範例（多語言）

# .usage-docs.yaml - 完整 UDS 配置
version: "1.0"
output:
  directory: "docs/"
  formats: [reference, cheatsheet]
  languages: [en, zh-TW, zh-CN]
  paths:
    en: "docs/"
    zh-TW: "locales/​zh-TW/​docs/"
    zh-CN: "locales/​zh-CN/​docs/"

sources:
  cli:
    enabled: true
    entry: "cli/​bin/​uds.js"
  skills:
    enabled: true
    directory: "skills/"
    pattern: "**/​SKILL.md"

單語言專案

僅需要英文文件的專案：

# .usage-docs.yaml - 僅英文
version: "1.0"
output:
  directory: "docs/"
  formats: [reference, cheatsheet]
  languages:
    - en
  paths:
    en: "docs/"

sources:
  cli:
    enabled: true
    entry: "src/​cli.js"

自訂語言配置

不同語言需求的專案（例如：英文 + 日文）：

# .usage-docs.yaml - 英文 + 日文
version: "1.0"
output:
  directory: "docs/"
  formats: [reference, cheatsheet]
  languages:
    - en
    - ja
  paths:
    en: "docs/"
    ja: "docs/​ja/"

templates:
  reference:
    title:
      en: "My Project Reference"
      ja: "プロジェクトリファレンス"
  cheatsheet:
    title:
      en: "My Project Cheatsheet"
      ja: "チートシート"

配置 Fallback 行為

產生器實作智慧 fallback 機制處理標題和路徑：

內建支援的語言：en、zh-TW、zh-CN

對於不支援的語言，您必須在 templates 區塊中提供自訂標題。

輸出檔案

整合到發布前檢查

將使用說明文件同步檢查加入 pre-release-check.sh：

# 檢查使用說明文件同步
echo "Checking usage documentation sync..."
./​scripts/​check-usage-docs-sync.sh

工作流程

┌─────────────────────────────────────────────────────────┐
│                      文件產生器                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  1. 載入配置 (.usage-docs.yaml)                         │
│           │                                              │
│           ▼                                              │
│  2. 掃描來源                                             │
│     ├─ CLI 指令 (uds.js)                                │
│     ├─ 技能 (SKILL.md 檔案)                             │
│     ├─ 命令 (斜線命令)                                   │
│     ├─ 代理 (代理定義)                                   │
│     ├─ 工作流程 (工作流程檔案)                           │
│     ├─ 核心規範 (core/​*.md)                             │
│     └─ 腳本 (scripts/​*.sh)                              │
│           │                                              │
│           ▼                                              │
│  3. 產生文件                                             │
│     ├─ FEATURE-REFERENCE.md（詳細版）                   │
│     └─ CHEATSHEET.md（速查表）                          │
│           │                                              │
│           ▼                                              │
│  4. 輸出各語言版本                                       │
│     ├─ 英文 (docs/)                                      │
│     ├─ 繁體中文 (locales/​zh-TW/​docs/)                   │
│     └─ 簡體中文 (locales/​zh-CN/​docs/)                   │
│                                                          │
└─────────────────────────────────────────────────────────┘

在其他專案使用

此技能設計為可重用。在你的專案中使用：

1. 複製配置範本：

   cp .usage-docs.yaml your-project/​.usage-docs.yaml
   

2. 修改為你的專案結構：

   • 更新來源目錄
   • 調整檔案命名模式
   • 配置輸出路徑

3. 複製產生器腳本：

   cp scripts/​generate-usage-docs.mjs your-project/​scripts/
   

4. 執行產生器：

   node scripts/​generate-usage-docs.mjs
   

相關規範

• 文件撰寫規範
• 文件結構規範
• AI 友善架構

版本歷史

---

授權

此技能以 CC BY 4.0 授權釋出。

來源: universal-dev-standards