# Refresh Agent Docs

> Use when refreshing, rewriting, syncing, or creating repository agent instruction files such as AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, Kiro steering, Roo rules, Codex instructions, or root project context docs.

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

---


# Refresh Agent Docs

Refresh repo agent guidance from current official docs without turning prompts into a markdown dump.

## Core Contract

- Fetch fresh official docs at the start of every run; do not rely on memory or an old cache.
- Keep one repo instruction source of truth when possible, usually `AGENTS.md`.
- Tool-specific files are adapters or scoped rules, not duplicated style guides.
- Root docs point to canonical details by relevance; they do not inline entire `CODE-STYLE.md`, `PROJECT.md`, `CONTEXT.md`, or `LANGUAGE.md`.
- Inspect `README.md` only for repo context. For README structure, landing docs, or public project onboarding, use `readme-editor`.
- Show a before/after plan and wait for approval before writing.

## Workflow

1. Inspect current repo docs: `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `PROJECT.md`, `CONTEXT.md`, `LANGUAGE.md`, `CODE-STYLE.md`, `README.md`, plus `.cursor/rules/`, `.kiro/steering/`, `.roo/rules*/`, and `.github/copilot-instructions.md`.
2. Refresh vendor guidance from this skill directory:

   ```bash
   node scripts/fetchOfficialAgentDocs.mjs
   ```

   Use the printed cache directory as the source set. If any source fails, report it; if every source fails, stop.
3. Compare tool behavior:
   - Codex/OpenAI, Cursor, Kiro, Roo, and other AGENTS-aware tools can share compact `AGENTS.md` guidance.
   - Claude Code needs `CLAUDE.md`; use `@AGENTS.md` only when `AGENTS.md` is intentionally compact.
   - Gemini CLI uses `GEMINI.md`; imports are useful but add prompt weight.
   - Cursor, Kiro, and Roo scoped-rule directories are for path/tool-specific rules, not copies of the whole root guide.
4. Propose the repo shape:
   - `AGENTS.md`: compact project contract, source-of-truth map, read order, verification, safety.
   - `CLAUDE.md` / `GEMINI.md`: adapters unless tool-specific behavior is genuinely needed.
   - scoped rules: only for large or path-specific guidance.
5. Render or write a before/after plan. Prefer `planpage` when available.
6. On approval, edit docs, then run `git diff --check` and the repo's relevant doc or verify commands.

## Output Rules

- Cite fetched source URLs in the summary.
- Never paste full vendor docs into repo files.
- Do not add backward-compat duplicate files "just in case"; replace or remove them in the same approved change.
- If repo docs conflict, surface the contradiction and ask which source wins before editing.

## Common Mistakes

| Mistake | Better behavior |
| --- | --- |
| Reusing remembered vendor behavior | Fetch official docs every run, then synthesize. |
| Copying full official docs into root files | Keep local docs short and repo-specific. |
| Making every tool file a full clone | Keep adapters tiny; put canonical guidance in one place. |
| Adding scoped rule folders by default | Add them only when scope changes behavior. |