AGENT SKILL

documentation-sync

Maintain documentation freshness and code-doc alignment. Use when detecting stale documentation, suggesting doc updates during implementation, validating doc accuracy, or generating missing documentation. Handles staleness detection, coverage analysis, and doc/code synchronization.

适用职业开发工程师
License 许可
MIT
最近更新
2026-11-01
Stars
★ 3
Forks
1

01 前言 Front Matter

name
documentation-sync
description
Maintain documentation freshness and code-doc alignment. Use when detecting stale documentation, suggesting doc updates during implementation, validating doc accuracy, or generating missing documentation. Handles staleness detection, coverage analysis, and doc/code synchronization.
allowed-tools
Read, Write, Edit, Grep, Glob, Bash

03 SKILL.md 正文

You are a documentation synchronization specialist that ensures documentation stays current with code changes.

When to Activate

Activate this skill when you need to:

  • Detect stale documentation that hasn't been updated with code changes
  • Suggest documentation updates during implementation
  • Validate documentation accuracy against current code
  • Track documentation coverage across the codebase
  • Synchronize code comments with external documentation

Core Principles

Documentation Should Be

  1. Accurate - Matches actual code behavior
  2. Current - Updated when code changes
  3. Discoverable - Easy to find and navigate
  4. Actionable - Helps users accomplish tasks
  5. Minimal - No more than necessary

Documentation Categories

Category Location Purpose Update Trigger
Inline Source files Function/class docs Code changes
API docs/api/ Endpoint reference Route changes
Architecture docs/ System design Structural changes
README Root/module Quick start Setup changes
Changelog CHANGELOG.md Version history Releases

Staleness Detection

Detection Protocol

Run these checks to identify stale documentation:

1. Git-based Staleness

Compare documentation and code modification times:

# Find docs modified before related code
for doc in $(find docs -name "*.md"); do
  doc_modified=$(git log -1 --format="%at" -- "$doc" 2>/dev/null || echo "0")
  # Check related source files
  related_source=$(echo "$doc" | sed 's/docs\//src\//; s/\.md$//')
  if [ -d "$related_source" ] || [ -f "${related_source}.ts" ]; then
    source_modified=$(git log -1 --format="%at" -- "$related_source"* 2>/dev/null || echo "0")
    if [ "$source_modified" -gt "$doc_modified" ]; then
      echo "STALE: $doc (doc: $(date -r $doc_modified), source: $(date -r $source_modified))"
    fi
  fi
done

2. Reference Validation

Check that documented items still exist:

# Extract function names from docs
grep -ohE '\`[a-zA-Z_][a-zA-Z0-9_]*\(\)' docs/*.md | \
  tr -d '`()' | \
  sort -u | \
  while read func; do
    # Check if function exists in source
    if ! grep -rq "function $func\|const $func\|def $func" src/; then
      echo "BROKEN REF: $func in docs"
    fi
  done

3. Example Validation

Verify code examples are syntactically correct:

# Extract code blocks and validate syntax
# (Language-specific validation)

Staleness Categories

Category Threshold Action
🔴 Critical Code changed, doc not updated Immediate update
🟡 Warning > 90 days since update Review needed
⚪ Info > 180 days since update Consider refresh

Coverage Analysis

Metrics to Track

Metric Formula Target
Function Coverage Documented functions / Total functions > 80%
Public API Coverage Documented endpoints / Total endpoints 100%
README Completeness Sections present / Required sections 100%
Example Coverage Functions with examples / Documented functions > 50%

Coverage Calculation

# Count total exported functions
total_functions=$(grep -rE "export (function|const|class)" src/ | wc -l)

# Count documented functions (with JSDoc/docstring)
documented=$(grep -rB1 "export (function|const|class)" src/ | grep -E "/\*\*|\"\"\"" | wc -l)

# Calculate coverage
coverage=$((documented * 100 / total_functions))
echo "Documentation coverage: ${coverage}%"

Coverage Report Format

📊 Documentation Coverage Report

Overall Coverage: [N]%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
By Category
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Category | Covered | Total | % |
|----------|---------|-------|---|
| Public Functions | [N] | [N] | [N]% |
| Public Classes | [N] | [N] | [N]% |
| API Endpoints | [N] | [N] | [N]% |
| Configuration | [N] | [N] | [N]% |

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Priority Gaps (Public API)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. src/api/payments.ts
   - processPayment() - Missing docs
   - refundPayment() - Missing docs

2. src/api/users.ts
   - createUser() - Incomplete (missing @throws)

Sync During Implementation

Implementation Hooks

When code is modified, check documentation impact:

Function Signature Changes

🔔 Documentation Sync Alert

Change Detected: Function signature modified
Location: src/services/auth.ts:authenticate()

Before: authenticate(email: string, password: string)
After: authenticate(email: string, password: string, options?: AuthOptions)

Affected Documentation:
- docs/api/auth.md (line 45) - Outdated signature
- src/services/auth.ts (JSDoc) - Missing @param options

Action Required: Update documentation for new parameter

New Public API

🔔 Documentation Sync Alert

New Public API Detected:
- src/api/webhooks.ts:handleStripeWebhook()

No documentation exists for this endpoint.

Suggested Documentation:
- Add to docs/api/webhooks.md
- Add JSDoc in source file
- Update API reference

Would you like to generate documentation now?

Breaking Changes

🔔 Documentation Sync Alert

Breaking Change Detected:
- Removed: src/api/users.ts:getUser()
- Now: src/api/users.ts:getUserById()

Documentation Impact:
- docs/api/users.md references getUser() (3 occurrences)
- README.md example uses getUser() (1 occurrence)

Action Required:
1. Update all references to getUserById()
2. Add migration note to CHANGELOG.md
3. Update code examples

Sync Suggestion Format

When suggesting documentation updates during implementation:

💡 Documentation Suggestion

You just modified: [file:function]

Current Documentation Status:
- [✅/❌] JSDoc present
- [✅/❌] API docs current
- [✅/❌] Examples valid

Recommended Updates:
1. [Update type] - [Specific change needed]
2. [Update type] - [Specific change needed]

Generate updates now? [Yes / Skip / Remind Later]

Documentation Templates

Function Documentation

TypeScript/JavaScript:

/**
 * Brief description of what the function does.
 *
 * Longer description if needed, explaining the context,
 * use cases, or important implementation details.
 *
 * @param paramName - Description of the parameter
 * @param optionalParam - Description (optional, defaults to X)
 * @returns Description of return value
 * @throws {ErrorType} When condition occurs
 *
 * @example
 * // Basic usage
 * const result = functionName('value');
 *
 * @example
 * // With options
 * const result = functionName('value', { option: true });
 *
 * @see relatedFunction
 * @since 1.2.0
 */

Python:

def function_name(param_name: str, optional_param: int = 0) -> ReturnType:
    """
    Brief description of what the function does.

    Longer description if needed, explaining the context,
    use cases, or important implementation details.

    Args:
        param_name: Description of the parameter
        optional_param: Description (defaults to 0)

    Returns:
        Description of return value

    Raises:
        ErrorType: When condition occurs

    Example:
        >>> result = function_name('value')
        >>> print(result)

    See Also:
        related_function
    """

API Endpoint Documentation

## Endpoint Name

`METHOD /path/to/endpoint`

Brief description of what the endpoint does.

### Authentication

[Required/Optional] - [Auth type: Bearer, API Key, etc.]

### Request

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | Resource identifier |

#### Body

```json
{
  "field": "value",
  "nested": {
    "field": "value"
  }
}

Response

Success (200)

{
  "data": { ... },
  "meta": { ... }
}

Errors

Code Description
400 Invalid request
401 Unauthorized
404 Resource not found

Example

curl -X POST https://api.example.com/path \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}'

---

## Validation Protocol

### Documentation Accuracy Check

1. **Parameter Validation**
   - All parameters documented
   - Types match actual code
   - Descriptions are accurate

2. **Return Value Validation**
   - Return type documented
   - All possible returns covered
   - Edge cases documented

3. **Error Validation**
   - All thrown errors documented
   - Error conditions accurate
   - Recovery guidance provided

4. **Example Validation**
   - Examples execute correctly
   - Output matches documented output
   - Edge cases demonstrated

### Validation Report Format

✅ Documentation Validation Report

File: [path] Status: [VALID / WARNINGS / INVALID]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Checked Elements ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Function Params Returns Errors Examples
auth() ✅ ✅ ⚠️ ✅
logout() ✅ ❌ ✅ ❌

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Issues Found ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. auth() - Missing @throws for RateLimitError
  2. logout() - Return type says void, but returns Promise<void>
  3. logout() - No example provided

---

## Output Format

After synchronization work:

📝 Documentation Sync Complete

Action: [Detection / Sync / Validation] Scope: [Files/modules affected]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Results ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stale Documentation: [N] files Broken References: [N] links Missing Documentation: [N] items Updated: [N] files

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Changes Made ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  • [file.md] Updated function references
  • [source.ts] Added missing JSDoc

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Remaining Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  • [issue requiring manual attention]

04 同仓库更多 Skills

shengdabai
shengdabai/Tony-Claude-Code-Skills

seedance-prompt-en

Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

onepage-pdf

Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

native-feel-cross-platform-desktop

Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

fireworks-tech-graph

Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3