实战一：构建一个 Docs Skill

---
name: docs-update
version: 0.1.0
description: |
  After code changes are staged or committed, check whether the related docs
  are still accurate. Propose doc patches where they drifted.
last_updated: 2026-07-19
---

# docs-update

## Trigger

Read this skill when EITHER:
  - The user has run `git commit` / `gh pr create` / `task release`
  - The user explicitly says "review 这个 diff" / "整理 PR"
  - After 8+ lines of diff in tracked source files

DO NOT read when:
  - User is asking an explanatory question
  - The diff is purely docs/comments changes
  - User explicitly says "no docs"

## Flow

1. Use `git diff --stat HEAD~1 HEAD` to get list of changed files.
2. Classify each changed file:
   - public API surface (exported fns/classes in src/)
   - CLI commands / args
   - configuration schema (yaml/toml keys)
   - private internals (less critical)
3. For each public-surface change, search docs/ for references:
   - rg "<function_name>" docs/
4. Propose doc patches in a `docs-changes-pending.md` artifact:
   - Old line: "..."
   - New line: "..."
   - File path

## DONE

When either:
  - docs/ unchanged in tracked files AND docs-changes-pending.md is empty
  - docs/ patches are written to docs-changes-pending.md and user confirms

## Failure Modes

- docs/ doesn't exist:
  - suggest "create docs/" with README + API.md templates
- docs are in another repo:
  - offer to open a sibling issue in that repo
- diffs are huge (>500 lines):
  - sample 50 random lines for docs references, don't check all

## Self-report

All responses from this skill MUST be prefixed with `[docs-update]`.

# API File Path → Doc File Mapping

## Python (src/...)
function `src/foo/bar.py::connect`  →  docs/api/foo.md#connect
class    `src/foo/baz.py::Client`    →  docs/api/foo.md#Client

## TypeScript (src/...)
export const  →  docs/api.md
export class →  docs/api.md

## CLI
cli.py:main args    →  docs/cli.md
config keys (yaml)  →  docs/config.md

# Anti-patterns to avoid

## Don't check tests/ folder for docs
Tests are not docs. Their public API changes don't need user docs update.

## Don't be exhaustive on internal files
Don't propose doc updates for `src/internal/foo.py` — those are not public surface.

## Don't generate new pages for unused code
If a new function is added but `_looks internal_` (prefixed `_`, lowercase only, etc.) → mark in docs-changes-pending.md as `[candidate for internalization]` instead.

# 改一个公开函数
# 修改 src/foo.py: def is_email(...)
# 让代码 commit

opencode
> commit 我刚加的 src/foo.py 的更严格 email 校验

[tdd-reminder skipped] reason: one-line fix                # 其他 skill
[docs-update] about to check docs
Discover changes:
  - src/foo.py (is_email, is_handle)
API mapping:
  - is_email → docs/api/foo.md#is_email
  - is_handle → docs/api/foo.md#is_handle
Existing docs refs:
  - docs/api/foo.md:42: "is_email(s): >=3 chars, accept + aliases"
Drift:
  - The change adds length limit 64 chars. Doc says no length limit.
Propose patch:
  docs/api/foo.md:42:
    - "is_email(s): >=3 chars, accept + aliases"
    + "is_email(s): 3-64 chars, accept + aliases"

[[probe]]
text = "commit 我刚加的 src/foo.py 的更严格 email 校验"
expect = "engaged"

[[probe]]
text = "为什么 Python 的 email 校验需要折腾?"
expect = "skipped"

[[probe]]
text = "整理这个 PR"
expect = "engaged"

[[probe]]
text = "如何用 RAG 找文档?"
expect = "skipped"

[[probe]]
text = "task release"
expect = "engaged"

import toml, subprocess, json

PROBES = toml.load("tests/probes.toml")["probe"]

def run_probe(probe_text: str) -> str:
    result = subprocess.run(
        ["opencode", "trigger-check", "--skill", "docs-update",
         "--probe", probe_text],
        capture_output=True, text=True,
    )
    return json.loads(result.stdout)["triggered"]

def test_probes():
    for p in PROBES:
        assert run_probe(p["text"]) == p["expect"], \
            f"probe failed: text={p['text']}, expect={p['expect']}"

# tests/test_behavior.py
import subprocess, pytest

@pytest.fixture
def setup_repo(tmp_path):
    # 创建一个 minimal git repo with src/foo.py + docs/api/foo.md
    (tmp_path / "src").mkdir()
    (tmp_path / "src" / "foo.py").write_text("def is_email(s): return True\n")
    (tmp_path / "docs").mkdir()
    (tmp_path / "docs" / "api").mkdir()
    (tmp_path / "docs" / "api" / "foo.md").write_text("# is_email\n>=3 chars, any aliases, no length limit\n")
    subprocess.run(["git", "init"], cwd=tmp_path, check=True)
    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
    subprocess.run(["git", "commit", "-m", "init"], cwd=tmp_path, check=True,
                   capture_output=True)
    # change the source
    (tmp_path / "src" / "foo.py").write_text("def is_email(s): return 3 <= len(s) <= 64\n")
    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
    subprocess.run(["git", "commit", "-m", "add length limit"], cwd=tmp_path, check=True,
                   capture_output=True)
    return tmp_path

def test_docs_update_proposes_patch(setup_repo):
    proc = subprocess.run(
        ["opencode", "--cwd", str(setup_repo), "oneshot",
         "review 我刚的改动, 看看 docs"],
        capture_output=True, text=True, timeout=120,
    )
    output = proc.stdout
    assert "[docs-update]" in output
    assert "3-64 chars" in output       # 应反映新 const
    assert "no length limit" in output  # 应指出旧 doc

{
  "name": "docs-update",
  "version": "0.1.0",
  "author": "your_org/ai-skills",
  "compatible_with": ["opencode>=0.5"],
  "skills": ["skills/docs-update"],
  "mcp": [],
  "hooks": []
}

name: Skill regression
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: opencode-ai/setup-opencode@v1
      - run: opencode trigger-check --skill skills/docs-update
      - run: pytest tests/
      - run: ruff check skills/

git tag v0.1.0 -m "first release"
git push origin v0.1.0
# 发布 release notes
gh release create v0.1.0 --generate-notes
# 同时更新 plugin repo

# 安装方:
opencode plugin install github:your_org/ai-skill-docs-update@v0.1.0

rg "\[docs-update\]" .opencode/log/ --since '3 weeks ago' | wc -l
# 应得成正比的数,如 27 次
rg "\[docs-update\]" .opencode/log/ | awk -F'reason:' '{print $2}' | sort | uniq -c
# 1 user-skip, 1 doc-in-other-repo, 25 engaged