Skip to content

omergocmen/vibe-coder-kit / .agent/skills/documentation-sync

documentation-sync

Verified

After any significant code change — new feature, API modification, config change, or architectural refactor — run this skill to identify which documentation files are now stale and update them. Keeps docs and code from drifting apart.

FileKindSize
SKILL.mdskill md4.9 KB
---
name: documentation-sync
description: >
  After any significant code change — new feature, API modification, config
  change, or architectural refactor — run this skill to identify which
  documentation files are now stale and update them. Keeps docs and code
  from drifting apart.
---

<!--
  TÜRKÇE AÇIKLAMA
  ───────────────
  Bu skill, kodda yapılan önemli değişikliklerden sonra hangi dokümantasyon dosyalarının
  eskidiğini tespit edip günceller. README, API docs, .env.example, CHANGELOG ve mimari
  diyagramlar incelenerek eski bilgiler düzeltilir. "Docs ile kod arasındaki uçurum"
  problemini kapatır.

  NE ZAMAN: API eklendiğinde/değiştiğinde, yeni env variable eklendiğinde,
            büyük refactor sonrası, merge öncesi veya sonrası.
  ÇIKTI:    Güncellenmiş doc dosyaları + değişim özet raporu.
-->

# Documentation Sync Skill

## When to Trigger

Run after:
- A public API endpoint is added, changed, or removed
- A CLI command or flag is modified
- A new environment variable or config key is introduced
- A major component or module is refactored
- A new npm/pip/etc. package is added or removed from dependencies
- Any `README.md` reference becomes inaccurate

## Step-by-Step Process

### 1. Identify What Changed

Review the git diff of the work just completed:

```bash
git diff main --name-only          # Files changed vs main
git diff HEAD~1 --name-only        # Files changed in last commit
```

Categorize changes:
- **API changes** → affects `docs/api/`, OpenAPI/Swagger specs, `README.md`
- **Config changes** → affects `.env.example`, `docs/configuration.md`
- **Dependency changes** → affects `README.md` (setup section), `docs/getting-started.md`
- **Architecture changes** → affects `docs/architecture.md`, diagrams
- **New features** → affects `docs/features/`, changelogs

### 2. Audit Existing Docs

For each affected category, check whether corresponding docs exist:

```
docs/
  api/             ← REST/GraphQL endpoint docs
  architecture.md  ← System design, component diagram
  configuration.md ← All env vars and config options
  getting-started.md ← Local setup guide
  features/        ← Per-feature descriptions
CHANGELOG.md       ← Version history
README.md          ← Project overview + quickstart
```

For each doc file that touches the changed area, read it and flag stale sections.

### 3. Update Docs — Priority Order

Update in this order (highest impact first):

#### A. README.md
- Setup instructions still accurate?
- Tech stack section reflects current stack?
- Any removed features still mentioned?

#### B. .env.example / Configuration Docs
For every new env variable added to code, add a corresponding entry:

```bash
# Description of what this does
NEW_VAR_NAME=example_value
```

Document in `docs/configuration.md`:
```markdown
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| NEW_VAR_NAME | Yes | — | What it controls |
```

#### C. API Docs
For every endpoint change, update the relevant doc:

```markdown
### POST /api/resource

**Changed in:** <date or version>
**Description:** ...
**Request Body:** ...
**Response:** ...
**Breaking Change:** Yes/No
```

#### D. CHANGELOG.md
Append an entry under `## [Unreleased]`:

```markdown
### Added
- <new feature description>

### Changed
- <what was modified and why>

### Fixed
- <bug fixed>

### Removed
- <what was removed>
```

Follow [Keep a Changelog](https://keepachangelog.com) format.

#### E. Architecture Docs
If a new service, module, or significant component was added:
- Update the component list in `docs/architecture.md`
- Note any new external dependencies or integrations
- If a diagram exists (Mermaid, Draw.io), update it

### 4. Verify Internal Links

After editing, do a quick check for broken internal references:

```bash
# Find markdown links pointing to non-existent files
grep -r "\[.*\](.*\.md)" docs/ README.md | grep -v "http"
```

Manually verify the top 5 most-used internal links still resolve.

### 5. Report Changes

Output a summary:

```
## Documentation Sync Complete

**Files Updated:**
- README.md — updated setup section
- docs/configuration.md — added NEW_VAR_NAME
- CHANGELOG.md — added unreleased entry

**Files That May Need Manual Review:**
- docs/architecture.md — diagram may be outdated (manual update needed)

**No changes needed:**
- docs/api/ — no endpoint changes detected
```

## Rules

- **Never delete documentation** without confirming with the user. Archive or mark as deprecated instead.
- **Don't invent information.** If you're unsure what a config variable does, write `# TODO: document this` and flag it.
- **Keep CHANGELOG.md under `[Unreleased]`** until an explicit version bump/release.
- **Every new env variable must appear in `.env.example`** — no exceptions.
- **Docs first is fine, but docs-never is not.** Even minimal docs are better than none.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall