skills.rest
NalinDalal
NalinDalalCOMMUNITY
Explore all skills by this author →
Website𝕏@nalin82929GitHub

agent-docs-writer

Writes and audits README.md and AGENTS.md documentation pairs for code repositories.

1|Updated Aug 17, 2026
Search Tags:#documentation#markdown#onboarding#readme#agents.md#repo audit#coding agents
One-click install
npx skills add https://github.com/NalinDalal/skillset --skill agent-docs-writer-nalindalal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-docs-writer
Source: https://github.com/NalinDalal/skillset/tree/main/skills/ai-agent/agent-docs-writer
Command: npx skills add https://github.com/NalinDalal/skillset --skill agent-docs-writer-nalindalal

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Repositories often lack documentation that helps AI coding agents and human contributors work safely, and existing README or AGENTS.md files drift out of sync with what actually shipped. This Skill produces a structured README.md and AGENTS.md pair that makes a codebase legible to agents like Claude Code, Cursor, Codex, and OpenCode. ## Core Features & Use Cases - Repo scanning and interview workflow: Scans package manifests, directory structure, tests, and CI config before asking targeted questions about glossary terms, non-negotiables, and architecture. - Dual-document generation: Drafts README.md as a decision document and AGENTS.md as an operating manual, using provided templates and drafting principles. - Plan-drift auditing: Reviews existing docs against actual code, distinguishing [planned] from [shipped] claims and marking drift with dated NOTE markers. - Use Case: Point the Skill at a new monorepo and ask it to write an AGENTS.md; it scans the repo, interviews you about hard invariants, shows a draft for confirmation, then writes both files. ## Quick Start Ask the agent to write an AGENTS.md and README for this repository so coding agents can safely make changes.

Frequently Asked Questions about agent-docs-writer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an AGENTS.md file for my repository?▼

Scan the repo for manifests, structure, tests, and CI config first, then interview the maintainer about glossary terms, non-negotiables, and good/bad examples. Draft from the AGENTS template, show it in chat for confirmation, and only write the file after approval.

What is the difference between README.md and AGENTS.md?▼

README.md is a decision document answering what the project is and whether to engage with it. AGENTS.md is an operating manual for agents or humans about to make changes, covering conventions, non-negotiables, and how the pieces fit together.

Does AGENTS.md work with Claude Code, Cursor, and Codex?▼

Yes, AGENTS.md is written to be discoverable by coding agents including Claude Code, Cursor, Codex, and OpenCode. Many of these tools auto-load AGENTS.md from the repo root, so the filename convention itself acts as the trigger.

How do I audit an existing README for stale or inaccurate claims?▼

Use the audit mode to compare doc claims against package.json, repo structure, tests, and CI config. Flag each unmarked claim that does not match the code with a dated NOTE marker instead of silently rewriting it, and ask the user whether it actually shipped.

When should a project include a glossary in AGENTS.md?▼

Include a glossary only when the project has overloaded or ambiguous terms whose meaning differs from casual usage. Keep each definition to one plain sentence, and skip the section entirely if the project has no non-obvious terminology.

Related Skills

Explore More Software Engineering Skills→
dotnetdotnet
5.3k

scaffold-dotnet-test-project

Creates, registers, and repairs .NET test projects for solution and CI test discovery.

Official
Advanced
Anders-planckAnders-planck

docs-management

Standardize technical documentation creation, review, and publishing with templates and validation.

Community
Intermediate
JNZader-VaultJNZader-Vault

technical-docs

Generate technical documentation with templates for ADRs, OpenAPI, runbooks, and READMEs.

Official
Intermediate
harleypigharleypig
3

write-documentation

Generate README, API references, and changelogs from source code.

Community
Advanced