Skip to main content
skill CX Codex

oma-docs — Claude Code skill: what it does, how to install

Verifies documentation links, syncs docs against Git diffs, and flags translation drift. Runs through the oma docs CLI or falls back to manual markdown parsing.

MIT ★ 1,472 updated 2026-11-05

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent
Open on GitHub

What oma-docs does

The skill manages documentation maintenance across four distinct modes: verify, sync, i18n, and lint. The default verify mode maps local link targets and image paths into docs/generated/doc-refs.json. In sync mode, it inspects staged changes or Git ranges like HEAD~1..HEAD to draft updates matching recent code edits.

Automated checks rely on the oma docs CLI, with lychee used optionally for HTTP URL testing. When the CLI is unavailable, the agent does not halt: it manually scans Markdown files for [text](path), href, and src attributes, explicitly logging web URLs as unverified scope.

Safety guardrails protect sensitive project files. Files matching .env*, credentials, and private keys never appear in diff reports or generated patches. The skill respects oma-docs: skip annotations and Git exclusions, treating ignored build outputs as skipped rather than broken paths.

What it helps with

  • find broken relative paths and image links in markdown files
  • update repository docs based on recent Git diffs
  • identify content drift across translated documentation
  • lint localized markdown prose for style issues

Example prompts for the agent

  • Check broken relative links across repository docs
  • Sync docs with changes in HEAD~1..HEAD
  • Inspect documentation for translation drift using i18n mode

How to install oma-docs

1Plugin marketplace

/plugin marketplace add first-fluke/oh-my-agent
/plugin install oma@oh-my-agent

This installs the whole oma plugin with all its skills

2Skills CLI (Vercel)

npx skills add first-fluke/oh-my-agent --skill oma-docs -a claude-code

3Manually: put the files in place

~/.claude/skills/oma-docs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/oma-docs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about oma-docs

How to install oma-docs in Claude Code?

Add the marketplace and install the plugin with /plugin marketplace add first-fluke/oh-my-agent followed by /plugin install oma@oh-my-agent. You can also run npx skills add first-fluke/oh-my-agent --skill oma-docs -a claude-code in your terminal.

What does oma-docs do?

It audits markdown references, syncs repository documentation against code diffs, and highlights translation drift or linting issues.

What happens if the oma docs CLI is missing?

The agent inspects markdown files manually by resolving link paths and image targets relative to each file. It flags missing local targets while reporting network URLs as unverified.

Source text

SKILL.md · MIT
---
name: oma-docs
description: Check 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)`, `![alt](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
1. Select mode, paths/diff, and authorization from the request. Read only the matching section of `resources/commands.md`.
2. Run `oma docs verify --json`, `oma docs sync <range> --json`, `oma docs i18n --json`, or `oma docs lint --json` as appropriate. For sync, use the requested range; otherwise staged changes, then `HEAD~1..HEAD`.
3. Inspect the structured results. Verify each proposed correction against current code and document context. Exclude secret-bearing files and values from patches and reports.
4. Apply corrections already authorized by the user or assigned task. In an active OMA docs-sync workflow, first record each patch's actual apply/skip action, rationale, and evidence with `docs.sync-patch-approval`; bind `instanceId` and verification `--instance` to the doc path plus current patch revision (workflow Step 4 owns the command template). Existing authorization remains sufficient. Ask only about material missing decisions or new scope; continue independent work while waiting.
5. 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 `references/_shared/core/execution-policy.md` for 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: `references/_shared/core/execution-policy.md` (when not already provided).

© First Fluke · MIT · first-fluke/oh-my-agent

Similar skills

All skills for Writing and docs →

From the same set69

The whole set →
database Enforces database schema design, normalization, indexing, and migration standards for SQL, NoSQL, and vector stores. Activates on .sql and .prisma files. CX Codex +1 ★ 1,472repo stars docs-curator docs-curator — a subagent that detects documentation drift and updates MD files when code changes. Catches broken references, proposes patches, and keeps docs/**/*.md aligned with the codebase. CX Codex ★ 1,472repo stars i18n-guide The i18n-guide rule sets how agents choose a response language and which project text gets localized. It fits workflows that need consistent language handling across user-facing output and code. CX Codex +1 ★ 1,472repo stars frontend frontend — a rule for React and Next.js projects: shadcn/ui components, Tailwind CSS v4, FSD-lite architecture, Server Components by default. CX Codex +1 ★ 1,472repo stars oma-scm oma-scm — a skill that gives an agent a safe process for commits, branches, merges and conflict resolution. Use it when repository history matters and a careless force-push is not an option. CX Codex +1 ★ 1,472repo stars oma-skill-creation oma-skill-creation is a Claude Code skill for building and refining OMA skills in SSL-lite format for Claude Code and Codex. It runs during authoring, routing reviews, and contract validation. CX Codex +1 ★ 1,472repo stars oma-mobile oma-mobile — a mobile-focused skill: it builds screens and widgets in Flutter or React Native, wires camera, GPS, push and offline handling, then runs the checks. CX Codex +1 ★ 1,472repo stars oma-debug oma-debug — a skill for Claude Code and Codex isolates bugs, writes targeted fixes, and creates regression tests. Runs when tests fail, services crash, or code suffers from race conditions. CX Codex +1 ★ 1,472repo stars

Project sponsors

Companies that keep this analytics open