| name | tdk-guides-update |
| description | Review or update TDK source guide docs with the accepted Progressive Workflow Guide format using `projects/tdk/.specify/docs/en/guides/index.md` as the route-map source of truth. Use when editing or auditing TDK guides, restructuring guide IA, creating route maps or scenario pages, scanning routed subfiles, checking guide links, or validating docs after an agent updated TDK guides. Default to check-only unless the user explicitly asks to patch docs. |
tdk-guides-update
Maintain TDK source guide docs with a narrow English-first workflow. This skill owns guide IA, workflow-page format, local link checks, and review/update guardrails.
It does not own skill catalog sync. Use tdk-skill-docs-sync for marketplace skill-to-docs catalog updates.
Scope
Allowed first-pass scope:
projects/tdk/.specify/docs/en/guides/- local link references inside
projects/tdk/.specify/docs/
Do not edit these unless the user explicitly expands scope:
projects/tdk-docs/projects/tdk/README.md- non-English folders such as
projects/tdk/.specify/docs/vi/
- future language folders such as
jp
- root
.agents/skills/ or .codex/
Language policy: update English docs first. After owner review/done, suggest generic sync steps for other language folders; do not enforce non-English fallback in v1.
When the user explicitly asks to translate or sync Vietnamese docs under docs/vi/, write natural Vietnamese with full diacritics. Do not strip accents. Preserve command names, flags, file paths, code blocks, frontmatter keys, and identifiers exactly.
Modes
Parse the request text:
| Mode | Triggers | Behavior |
|---|
check-only | default, "check", "audit", "review only", "dry run" | Read docs and report mismatches. No file edits. |
review | "review and fix if safe" | Report findings; patch only small obvious issues if user allowed edits. |
update | "update", "rewrite", "apply", "normalize" | Patch English guide docs after running checklist and link inventory. |
If mode is unclear, use check-only.
Required References
Load only what the task needs:
references/workflow-guide-format.md when creating or updating route maps or workflow pages.references/guide-page-type-rules.md when deciding whether content is workflow, concept, reference, setup, or troubleshooting.references/guide-review-checklist.md for check-only/review runs and before final handoff.
Workflow
Step 1: Route-Map-First Scout
Treat projects/tdk/.specify/docs/en/guides/index.md as the guide-area source of truth.
If guides/index.md is missing, report a blocking finding. In update mode, create the minimal route map first from existing guide pages and local docs links; do not create or preserve projects/tdk/.specify/docs/en/index.md as a duplicate guide route map, and do not restructure subfolders blindly.
Run:
test -f projects/tdk/.specify/docs/en/guides/index.md && sed -n '1,220p' projects/tdk/.specify/docs/en/guides/index.md || true
test -f projects/tdk/.specify/docs/en/guides/index.md && rg -n "\\[[^]]+\\]\\([^)]+" projects/tdk/.specify/docs/en/guides/index.md || true
find projects/tdk/.specify/docs/en/guides -type f -name '*.md' | sort
git -C projects/tdk status --short
Build a route inventory before editing:
| Route map link | Resolved path | Exists? | Page type | Action |
|---|
Then scan all Markdown files under guides/ and list files not routed by guides/index.md:
| Unrouted file | Page type | Proposed action |
|---|
Read guides/index.md first, then read every linked guide page, then read unrouted candidate files only when deciding keep/rename/shim/delete. The TDK repo may already have user edits; preserve unrelated changes.
Step 2: Link Inventory Before Renames
Before renaming or replacing landing pages, run:
rg -n "setup/index.md|scenarios/index.md|concepts/index.md|epic-start-guide.md" projects/tdk/.specify/docs
Update local docs links or keep compatibility shims. Defer README, docs-site, and non-English sync.
Step 3: Check Or Update
For check-only:
- Read
guides/index.md first.
- Extract and resolve every Markdown link from
guides/index.md.
- Read each routed file and classify it with the page-type rules.
- Scan all
guides/**/*.md files and identify unrouted or duplicate landing pages.
- Compare routed pages and unrouted files against the references.
- Return findings grouped by route inventory, stale/missing routes, unrouted files, workflow pages, named landings, local links, long-page split risk, and language sync.
- Do not modify files.
For update:
- Confirm check-only output exists or run it first.
- Patch only English guide docs.
- Update
guides/index.md first and keep it route-only.
- Use route-map links to decide which subfiles need updates; do not infer priority from folder names alone.
- Use named landing pages such as
setup-guide.md and scenario-catalog.md; link concept pages only when they add unique non-workflow value.
- Keep
index.md shims only when local link inventory or renderer behavior requires them; otherwise route to named pages.
- Avoid broad prose rewrites that do not directly support the accepted IA.
Step 4: Validate
Run:
rg -n "setup/index.md|scenarios/index.md|concepts/index.md|epic-start-guide.md|scenario-catalog|promote-convention|glossary|setup-guide" projects/tdk/.specify/docs
test -f projects/tdk/.specify/docs/en/guides/index.md && rg -n "\\[[^]]+\\]\\([^)]+" projects/tdk/.specify/docs/en/guides/index.md
find projects/tdk/.specify/docs/en/guides -type f -name '*.md' | sort
If this skill itself was edited, mirror-check both local skill surfaces:
diff -qr projects/tdk/.agents/skills/tdk-guides-update projects/tdk/.claude/skills/tdk-guides-update
Output
For check-only/review:
## TDK Guides Check
### Scope
- Mode:
- Files read:
### Route Inventory
| Route map link | Resolved path | Exists? | Page type | Action |
|---|---|---|---|---|
### Unrouted Files
| File | Page type | Proposed action |
|---|---|---|
### Findings
| Area | Severity | Finding | Suggested fix |
|---|---|---|---|
### Do Not Edit Yet
- Non-English sync:
- Docs-site sync:
### Unresolved Questions
- None, or list questions.
For update:
- list changed files
- list validation commands and results
- list deferred language/doc-site sync suggestions
- list unresolved questions at the end
