AgentSkillsCN

doc-structure

專案文檔結構管理工具，用於建立、維護和驗證專案的層級聚攏文檔結構。 使用時機： - 當需要建立新的 README.md 文件 - 當需要為程式檔案添加標準化開頭註解 - 當重構或更新專案文檔結構 - 當需要驗證 README 連結有效性 - 當需要檢查文檔結構完整性 關鍵字：README、文檔結構、層級聚攏、檔案註解、連結驗證、結構檢查

中文原作
SKILL.md
--- frontmatter
name: doc-structure
description: |
  專案文檔結構管理工具，用於建立、維護和驗證專案的層級聚攏文檔結構。
  使用時機：
  - 當需要建立新的 README.md 文件
  - 當需要為程式檔案添加標準化開頭註解
  - 當重構或更新專案文檔結構
  - 當需要驗證 README 連結有效性
  - 當需要檢查文檔結構完整性
  關鍵字：README、文檔結構、層級聚攏、檔案註解、連結驗證、結構檢查

文檔結構管理 Skill

設計意義

標準化專案文檔結構，確保所有 README 和檔案註解格式一致，避免資訊重複和認知負擔。

核心理念：層級聚攏結構

code
CLAUDE.md（根）─ 專案規範 + 頂層目錄索引
    │
    ├── {dir}/README.md（上層）─ 設計意義 + 索引 + 參考
    │       │
    │       └── {subdir}/README.md（下層）─ 設計意義 + 索引 + 參考
    │               │
    │               └── {file}.js ─ 檔案頂部註解（Position + Input + Output + 職責）

三個原則：

  1. •上層索引下層：每個 README 只負責索引直接下層內容
  2. •設計意義穩定：說明「為什麼」，不隨程式修改而變
  3. •重構才重寫：只有架構變動時才更新設計意義

使用流程

建立新 README

  1. •確定目錄層級（頂層 or 子目錄）
  2. •讀取對應模板：
  3. •填入三個必要欄位：設計意義、索引、參考
  4. •確認不包含禁止內容

添加檔案註解

  1. •

    確定檔案類型，選擇對應模板：

    語言模板
    JavaScript/TypeScriptheader-js.txt
    Pythonheader-py.txt
    Dartheader-dart.txt
    Goheader-go.txt
    HTMLheader-html.txt
    PHPheader-php.txt
    Javaheader-java.txt
    C# (.NET)header-csharp.txt
    YAMLheader-yaml.txt
    Shell/Bashheader-shell.txt

    不支援註解的格式：JSON、Markdown、純資料檔案 → 由 README 說明

    自動排除：名稱包含 log 的資料夾和檔案（不區分大小寫）

  2. •

    填入四個必要欄位：

    • •Position：功能定位（在系統架構中的位置和角色）
    • •Input：外部依賴（依賴哪些模組或服務）
    • •Output：對外提供（導出的介面、類別或函數）
    • •職責：做什麼（1-3 項主要職責）

驗證工具

連結驗證

驗證所有 README.md 的內部連結是否有效：

bash
# 使用當前目錄
uv run validate-readme-links.py

# 指定專案路徑
uv run validate-readme-links.py /path/to/project

結構檢查

檢查預期的 README.md 是否存在：

bash
# 使用當前目錄
uv run check-doc-structure.py

# 指定專案路徑
uv run check-doc-structure.py /path/to/project

參考文檔