Skip to main content
skill CX Codex

writing-agents-md — Claude Code skill: write and audit agent instructions

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.

no license 305 installs ★ 655 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pedronauck/skills --skill writing-agents-md -a claude-code
Open on GitHub

What writing-agents-md 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.

What it helps with

  • 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 for the agent

  • 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

How to install writing-agents-md

1Skills CLI (Vercel)

npx skills add pedronauck/skills --skill writing-agents-md -a claude-code

2Manually: put the files in place

~/.claude/skills/writing-agents-md/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/writing-agents-md/

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

Questions about writing-agents-md

How do I install writing-agents-md in Claude Code?

Run npx skills add pedronauck/skills --skill writing-agents-md -a claude-code. The skill will be at ~/.claude/skills/writing-agents-md/SKILL.md.

What does writing-agents-md do?

It helps you write and review agent instruction files (AGENTS.md, CLAUDE.md). It teaches how to distinguish important rules from duplicates and outdated ones, remove what is not needed, and move lengthy explanations into focused skills.

How is writing-agents-md different from just editing instructions manually?

The skill gives you a system: verify each rule is actually needed and only in the right place, resolve conflicts, and account for context size across different tasks. Manual editing can leave duplicate or outdated rules behind.

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set52

The whole set →
writing-skills Walks the agent through writing, refactoring and debugging skills, and through finding out why a reference file never loaded. CX Codex +1 338installs storybook-stories Writes and edits Storybook stories the way your repo already does it. Handy once a project has plenty of stories and the naming rules live only in people's heads. CX Codex +1 317installs ui-craft ui-craft — a skill for designing and building visible interfaces: pages, components, forms, loading and error states, AI chat surfaces with streaming. Works within your project's design system and validates accessibility. CX Codex +1 314installs electron-dev electron-dev guides agents through building Electron apps with Electron Vite and Electron Builder. It focuses on process separation, IPC safety, and native dependencies. CX Codex +1 311installs app-renderer-systems The app-renderer-systems skill structures frontend modules in systems/ directories with clear layers: adapters, Query hooks, local state, and public exports. CX Codex +1 299installs rust-best-practices rust-best-practices — a skill for writing, refactoring, and optimizing Rust code with ownership, error handling, Tokio, traits, and testing. Use it for systems programming or async workloads where correctness matters. CX Codex +1 298installs es-toolkit Guides your AI assistant to use es-toolkit utility functions for arrays, objects, and strings instead of custom helpers. CX Codex +1 293installs extreme-software-optimization The extreme-software-optimization skill locates performance hot spots with measurements, then checks that changes preserve behavior. Use it for slow code, latency, throughput, or algorithm work. CX Codex +1 286installs

Project sponsors

Companies that keep this analytics open