flowchart TD
    A[启动: 加载所有技能的 name+description] --> B{用户发请求}
    B -->|描述命中| C[触发目标技能]
    C --> D[读取 SKILL.md 正文]
    D --> E{需要更多细节?}
    E -->|是| F[按需读 reference / 执行 scripts]
    E -->|否| G[执行任务]
    F --> G
    B -->|描述不命中| H[该技能文件零 token 占用]

documenting-functions/
├── SKILL.md            # 主指令（触发后才加载）
├── reference/          # 参考资料（按需加载）
│   ├── python.md
│   ├── javascript.md
│   └── go.md
└── scripts/            # 工具脚本（执行，不进上下文）
    └── extract_signatures.py

✅ 好：Generates docstrings for Python functions and adds JSDoc to JS methods.
❌ 坏：I can help you write docstrings.
❌ 坏：You can use this skill to document functions.

# PDF 处理
✅ Extract text and tables from PDF files, fill forms, merge documents.
   Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

# Excel 分析
✅ Analyze Excel spreadsheets, create pivot tables, generate charts.
   Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

# Git 提交
✅ Generate descriptive commit messages by analyzing git diffs.
   Use when the user asks for help writing commit messages or reviewing staged changes.

description: Helps document code.

description: Generates standards-compliant docstrings and API comments for
  functions and methods — Google/NumPy/Sphinx style for Python, JSDoc for
  JavaScript/TypeScript, godoc for Go. Use when the user asks to document,
  annotate, or add docstrings/comments to a function, class, method, or
  module, or when improving API documentation coverage.

# ❌ 太啰嗦（约 150 token）
PDF（便携式文档格式）是一种常见的文件格式，包含文本、图像等内容。
要提取文本，你需要用一个库。有很多库可以选，pdfplumber 比较好用……

# ✅ 精简（约 50 token）
## 提取 PDF 文本
用 pdfplumber：
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

mkdir -p ~/.claude/skills/documenting-functions/{reference,scripts}

---
name: documenting-functions
description: Generates standards-compliant docstrings and API comments for
  functions and methods — Google/NumPy/Sphinx style for Python, JSDoc for
  JavaScript/TypeScript, godoc for Go. Use when the user asks to document,
  annotate, or add docstrings/comments to a function, class, method, or
  module, or when improving API documentation coverage.
---

# Documenting Functions

## Quick start
1. Determine the target language from the file extension.
2. Run the signature extractor to inventory every function.
3. Write a docstring/comment following that language's convention.

## Conventions
- **Python** (.py): Google-style docstrings → see [reference/python.md](reference/python.md)
- **JavaScript/TypeScript** (.js/.ts/.tsx): JSDoc → see [reference/javascript.md](reference/javascript.md)
- **Go** (.go): godoc conventions → see [reference/go.md](reference/go.md)

## Signature extraction
List every function/method and its parameters before writing docs:

    python scripts/extract_signatures.py path/to/file.py

## Rules
- Document every **public** function or method. Skip names starting with `_`
  unless the user explicitly asks.
- Infer parameter and return types from the code; mark unknowns as `(unknown)`
  rather than guessing.
- Keep summaries to one imperative sentence.

## Workflow checklist
Copy and track your progress:

    [ ] Identified the language
    [ ] Extracted signatures
    [ ] Wrote a docstring for each public function
    [ ] Listed Args / Returns / Raises (or the language equivalent)
    [ ] Did not document trivial one-line getters

# Python docstrings (Google style)

## Template

    """One-line summary in imperative mood.

    Optional extended description.

    Args:
        param_name (type): Description.

    Returns:
        type: Description.

    Raises:
        ExceptionType: When this happens.
    """

## Rules
- First line ends with a period and fits on one line.
- Document every argument, return value, and raised exception.

# JSDoc

## Template

    /**
     * One-line summary.
     *
     * @param {Type} paramName - Description.
     * @returns {Type} Description.
     */

## Rules
- Always include @param and @returns for non-void functions.
- Use {Type} braces for type annotations.

#!/usr/bin/env python3
"""List every function/method signature in a Python file."""
import ast
import sys


def main(path: str) -> None:
    try:
        with open(path, encoding="utf-8") as f:
            tree = ast.parse(f.read(), filename=path)
    except FileNotFoundError:
        print(f"file not found: {path}", file=sys.stderr)
        sys.exit(1)

    for node in ast.walk(tree):
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
            args = [a.arg for a in node.args.args]
            kind = "method" if isinstance(node, ast.FunctionDef) else "function"
            print(f"{kind} {node.name}({', '.join(args)})  # line {node.lineno}")


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("usage: extract_signatures.py <file.py>", file=sys.stderr)
        sys.exit(1)
    main(sys.argv[1])

帮我把 utils.py 里所有函数都补上规范文档

{
  "skills": ["documenting-functions"],
  "query": "Add Google-style docstrings to every public function in utils.py",
  "files": ["utils.py"],
  "expected_behavior": [
    "Reads utils.py and lists all public functions (skips names starting with _)",
    "Generates Google-style docstrings with Args/Returns/Raises sections",
    "Infers parameter and return types from the code",
    "Does not document trivial one-line getters unless asked"
  ]
}

flowchart TD
    A["Claude A（作者）: 撰写/改进 SKILL.md"] --> B["Claude B（执行者）: 带上技能跑真实任务"]
    B --> C{观察 Claude B 行为}
    C -->|发现问题| D["记录: 哪里没触发 / 哪里出错 / 漏读哪个文件"]
    D --> A
    C -->|表现良好| E[发布或分享给团队]

flowchart LR
    A["1.命名与定位<br/>(gerund, ≤64, 禁保留词)"] --> B["2.写 description<br/>(第三人称+what+when)"]
    B --> C["3.选自由度<br/>(高/中/低)"]
    C --> D["4.写正文<br/>(精简, ≤500行)"]
    D --> E["5.组织多文件<br/>(渐进式披露, 一层深)"]
    E --> F["6.加脚本<br/>(自己处理错误)"]
    F --> G["7.评测迭代<br/>(Claude A↔B)"]
    G -->|未达标| B
    G -->|达标| H[发布/分享]