# Docs Agent Md

> Create, refresh, or reconcile the repository root `AGENTS.md` using current branch truth. Use when Codex needs to update `AGENTS.md` after code, config, CI, audit, or documentation changes, or when the repo's agent guidance must be checked against current files without widening scope to the rest of the docs set. Use when this capability is needed.

- Skill: `tomevault-io/docs-agent-md` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/docs-agent-md`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/docs-agent-md/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/docs-agent-md

---


# Docs Agent MD

Use this skill to maintain the repository root `AGENTS.md` as a minimal,
repo-grounded document.

## Required Inputs

- Repository root containing `AGENTS.md`
- Current branch files used as source of truth

If `AGENTS.md` is missing, create it at the repository root and still keep the
scope limited to that file.

## Audit Check

Before updating `AGENTS.md`, determine the current local date in `YYYY-MM-DD`
format and inspect `docs/audit/`.

- If any audit filename starts with today's date, treat that as the current
  audit input.
- If no audit filename starts with today's date, ask the user whether to run
  `$docs-audit` before continuing.
- If the user wants the audit, use `$docs-audit` first and then continue with
  the refreshed report.

Accept both date-only and timestamped report names, for example:

- `docs/audit/2026-03-24.md`
- `docs/audit/2026-03-24_09:15:00.md`

## Workflow

1. Read the current `AGENTS.md`.
2. Check for a same-day audit in `docs/audit/`.
3. Inspect current repository truth before editing:
   - `git status --short`
   - recent commits such as `git log --oneline -n 10`
   - runtime and config files referenced by `AGENTS.md`
   - CI and policy files referenced by `AGENTS.md`
4. Use `references/agents-md-template.md` as the required output structure.
5. Update only `AGENTS.md`.
6. Re-read the final file for structure, wording, and claim accuracy.

## Content Rules

- Keep the document grounded in repository-observable facts.
- Prefer code, config, and CI over prose docs when they conflict.
- Preserve the current 5-section layout unless the user explicitly asks for a
  different structure.
- Keep the document minimal; avoid expanding it into a policy manual.
- State when a rule is observed guidance rather than hard enforcement.
- Do not invent ownership, deployment guarantees, or runtime behavior.

## Section Contract

Follow the exact section order in `references/agents-md-template.md`:

1. `## 1. Purpose`
2. `## 2. Repository Overview`
3. `## 3. Agent Roles`
4. `## 4. Coding Standards`
5. `## 5. Safety & Constraints`

## Boundaries

Allowed work:

- Read docs, audits, code, config, CI, and git metadata needed to verify
  `AGENTS.md`
- Update `AGENTS.md`

Default write scope:

- `AGENTS.md` only

Do not do this by default:

- Rewrite broader repository docs
- Edit `.github/workflows/*`, policy files, or API contract artifacts as part of
  an `AGENTS.md` refresh
- Expand the task into a full docs audit when the user only asked for
  `AGENTS.md`

## Redirects

- Use `$docs-audit` for full documentation accuracy audits and dated audit
  reports in `docs/audit/`.
- Use `$docs-feature` for `docs/features/*` authoring and index reconciliation.
- Use other repository docs skills when the target is not the root `AGENTS.md`.

## Bundled Resources

- `references/agents-md-template.md`: Required output template and section
  intent for the root `AGENTS.md`.

---
> Source: [CMSgov/emmy-api](https://github.com/CMSgov/emmy-api) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->