gracefullight/pkgs / .agents/skills/oma-docs
oma-docs
VerifiedCheck documentation references, sync docs to code changes, and detect translation drift. Use for documentation maintenance in a repository.
Documentation Maintenance
Scheduling
Goal
Keep documentation aligned with repository behavior and report verification limits.
Intent signature
Check references, update docs for a code diff, identify translation drift, or lint localized prose.
When to use
Repository documentation verification, diff-based synchronization, and translation maintenance.
When NOT to use
- General source research -> oma-search.
- Application implementation -> the owning specialist.
- Translating known text -> oma-translation.
Expected inputs
Mode (verify, sync, i18n, or lint), target paths or diff range, and authorized edit scope. Use verify when no mode is specified.
Expected outputs
Findings with paths and evidence, authorized patches when requested, and unresolved checks. CLI reports remain distinct from host-authored interpretation.
Dependencies
The oma docs CLI, Git for diff-based work, and repository docs. lychee is optional for URL verification. Read resources/commands.md for flags and output files of the selected mode.
Structural Flow
Transitions
verify: extract and resolve references, then summarize the report.sync: obtain candidates, read relevant docs and diffs, and apply only authorized corrections.i18n/lint: report drift or style issues; use oma-translation for authorized corrections.- Review-only requests produce proposals. Existing scoped edit requests authorize applying those corrections without another per-file approval.
Failure and recovery
| Failure | Recovery |
|---|---|
| Missing CLI | State up front that the automated check is unavailable, then inspect manually anyway: list the target markdown files, extract [text](path), , and href/src targets, resolve each relative to its containing file, and report which resolved paths are missing. Skip http(s) URLs and note them as unverified scope. Label the result "manual inspection — oma docs verify did not run"; never present it as CLI output and never make installing the CLI a prerequisite |
| Missing lychee or incomplete URL scan | Report core results and the unverified URL scope |
| One document cannot be parsed | Record the skipped file and continue other documents |
| Patch does not apply | Re-read the affected current content and make the equivalent authorized correction |
| Index write fails | Report the failure; do not claim the index or check is complete |
Exit
Report verified findings, edits made, and remaining gaps. A clean reference scan does not establish semantic correctness or complete translation quality.
Logical Operations
Canonical command path
- Select mode, paths/diff, and authorization from the request. Read only the matching section of
resources/commands.md. - Run
oma docs verify --json,oma docs sync <range> --json,oma docs i18n --json, oroma docs lint --jsonas appropriate. For sync, use the requested range; otherwise staged changes, thenHEAD~1..HEAD. - Inspect the structured results. Verify each proposed correction against current code and document context. Exclude secret-bearing files and values from patches and reports.
- Apply corrections already authorized by the user or assigned task. Ask only about material missing decisions or new scope; continue independent work while waiting.
- Re-run affected checks after edits and record remaining failures. Regenerate the reference index once after a patch batch when needed.
Resource scope and effects
Verification regenerates docs/generated/doc-refs.json; optional URL results go to docs/generated/url-drift.json. Sync's CLI emits candidate data; the host drafts and applies patches. i18n/lint commands report only. A workflow hook runs only when docs.auto_verify is enabled and is warn-only.
Guardrails
- Follow
../_shared/core/execution-policy.mdfor authorization and completion. - Keep review-only requests read-only and changes within the assigned diff or acceptance criteria.
- Do not expose secret-bearing files (
.env*, private keys, credentials) in diff reports. - The CLI produces structured data; the host performs natural-language synthesis. Do not invent CLI findings or call a vendor LLM API from the docs CLI.
- Honor ignore blocks,
oma-docs: skip, and configured exclusions. Missing gitignored runtime outputs are skipped, not broken references. - Preserve language, terminology, and placeholders when applying localized corrections.
References
- Mode commands, flags, and outputs:
resources/commands.md(selected operation only). - Translation:
../oma-translation/SKILL.md(localized correction). - Authorization:
../_shared/core/execution-policy.md(when not already provided).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 465k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |