# writing-agents-md

writing-agents-md is a Claude Code skill for writing and reviewing AGENTS.md and CLAUDE.md files. It covers projects with rules agents cannot infer from code or tooling alone.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 305 installs · ★ 655 repo stars
- Author: Pedro Nauck
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/writing-agents-md/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/writing-agents-md

## What it does

The skill teaches agents what belongs in agent instructions and what does not. Focus on the non-obvious: custom commands, expensive constraints, domain vocabulary, project-specific compatibility decisions. Rules that overlap or grow stale should be removed, refined, or moved to narrower skills.

The method has five steps: read instructions and the repo, review rules (keep, rewrite, relocate, or remove), resolve conflicts, edit the canonical file, and verify important invariants remain reachable. The skill optimizes for context size per representative task, not line count alone. Output a summary of what changed and any remaining tradeoffs.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-agents-md -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/writing-agents-md/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/writing-agents-md/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-agents-md -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/writing-agents-md/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-agents-md -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/writing-agents-md/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pedronauck/skills skills/mine/writing-agents-md
```

2. **Manually: put the files in place**
- File: `.github/skills/writing-agents-md/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-agents-md -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pedronauck/skills --path skills/mine/writing-agents-md
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/writing-agents-md/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pedronauck/skills --skill writing-agents-md -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pedronauck/skills/tree/HEAD/skills/mine/writing-agents-md/SKILL.md

## When to use it
- Remove stale rules from agent instructions
- Resolve contradictions between commands in AGENTS.md
- Move long rationale into separate skills or links
- Keep only what the agent cannot infer from code
- Reduce instruction context load for typical workflows

## Example prompts
- Audit AGENTS.md in this repo: drop stale rules and move conflicts into skills
- Write CLAUDE.md for the project based on current rules in README and code comments
- Check that all commands in .agents/skills align with AGENTS.md

## Similar
- [qi-layer](https://affpapa.org/en/nevibecode/skills/qi-layer.md) — skill · 441 installs
- [agents-md](https://affpapa.org/en/nevibecode/skills/mblode-agents-md.md) — skill · 927 installs
- [reflect](https://affpapa.org/en/nevibecode/commands/john-rogers-at-johnrogers-reflect.md) — command · ★ 233 repo stars
- [update-docs-on-code-change](https://affpapa.org/en/nevibecode/rules/update-docs-on-code-change.md) — rule · ★ 41430 repo stars
- [exclude-prompt-data](https://affpapa.org/en/nevibecode/rules/exclude-prompt-data.md) — rule · ★ 41430 repo stars
- [decision-doc-sync](https://affpapa.org/en/nevibecode/skills/decision-doc-sync.md) — skill · 5700 installs

From the same set: [pedronauck/skills](https://affpapa.org/en/nevibecode/by/pedronauck/skills.md) — 52 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
