OpenSkillIndex← back to search
claude-codeproductivity

Claude-skill-registry doc-structure

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/doc-structure" ~/.claude/skills/majiayu000-claude-skill-registry-doc-structure && rm -rf "$T"
manifest: skills/data/doc-structure/SKILL.md
tags
#documentation#file-management#code-standards#markdown#automation#linting
source content

文檔結構管理 Skill

設計意義

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

核心理念：層級聚攏結構

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 的內部連結是否有效：

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

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

結構檢查

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

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

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

參考文檔