How to use the AGENTS.md Generator agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file and supporting files. When installed, the AI agent reads these instructions and follows them for matching tasks. This skill, named agents-generator, is for projects that use AGENTS.md, a plain Markdown file that tells AI coding tools how to work in a repository.

Once triggered, the agent detects your package manager from lockfiles, reads package.json scripts and non-secret config files, and explores the folder layout. It then writes a project-specific AGENTS.md and, in full mode, optional rule files under .agents/rules/. The skill states that it is designed to produce a tailored document rather than a template with placeholders.

• Detects the package manager from bun.lock, pnpm-lock.yaml, package-lock.json or yarn.lock, and never defaults to npm.
• Documents setup commands, verification steps and conventions taken from your project files.
• Can generate rule files for detected areas such as frontend patterns, server actions, testing, git workflow and SDD workflow.
• Supports monorepos, managed blocks, timestamped backups and confidence scoring.

Install the agents-generator skill

Download the skill ZIP from the page where you found this guide. Then choose one of the install routes below. Use the personal folder if you want the skill available in every project, or the project folder if you want it limited to one repository.

In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

• Personal install: unzip the file into ~/.claude/skills/.
• Project install: unzip the file into the .claude/skills/ folder of your project.
• App install: upload the ZIP under Settings, then Capabilities, then Skills.

Check your project before you run it

The skill works on a Git repository. It uses git rev-parse --show-toplevel to find the project root, so run it from inside a repo. It also needs permission to read and write files in the target project and to run the shell tools listed in its allowed tools: ls, git, tree, find, grep and glob search.

Know that the skill lists WebFetch among its allowed tools, so it has network access. Its metadata gives it a critical risk label and states that it uses the network. Because of this, use it only in projects you are authorised to change.

• Git repository with a project root.
• File read and write access to the target project.
• Shell tools: ls, git, tree, find, grep, glob search.
• WebFetch network access, which is listed in allowed tools.
• The skill does not run project scripts.

Trigger the skill with natural requests

You do not need special syntax. Ask in plain language and the agent chooses the mode. Full mode is the default when you do not name one. Minimal mode writes a single file of about 30 lines with no rule files. Update mode re-checks the project and regenerates only the parts that changed. Dry-run mode runs all detection but writes nothing.

• Full: 'create a complete AGENTS.md for this project' or 'full AGENTS.md with rules'.
• Minimal: 'simple AGENTS.md', 'just the basics' or 'minimal'.
• Update: 'update AGENTS.md', 'refresh' or 'my stack changed'.
• Dry-run: 'preview' the AGENTS.md, 'show what would change' or 'dry-run' it.

Preview changes with dry-run before writing anything

Dry-run is the safest first step, especially if you have existing agent instructions. The skill performs detection and then reports the detection summary, the files that would be created, the rules it would skip and sample output. No files are written.

Review the preview, then ask for the real run if the output looks right.

• Ask for a dry-run or preview before the first full run.
• Check which rules are skipped and why.
• Read the sample output against your actual project.

Review the output, backups and approval step

The skill's instructions say to read the detected inputs and proposed outputs first and to get approval before changing target files. Existing files are backed up as timestamped copies outside the rule discovery paths. The skill refuses symlinked target files or parent folders. In update mode it replaces only one well-formed managed block, marked by AGENTS-GENERATED-START and AGENTS-GENERATED-END comments, and keeps everything outside it. If the markers are missing, duplicated or malformed, it proposes a diff instead of overwriting.

Generated conventions are proposals. New conventions are labelled, and the skill does not infer approval, attribution, branch, release or review rules from dependencies. Review everything before you commit it.

• Check the backups exist before accepting changes.
• Confirm every command is one that exists in package.json scripts.
• Treat new conventions as suggestions until a person approves them.
• Scan the output for leftover placeholders; the skill is designed to reject them.

Read the example output

The skill's documentation shows an example project built with Bun, Next.js, Tailwind, Vitest and Server Actions. For that project it produces an AGENTS.md with setup commands, a verification cycle and a link to an architecture rule file, plus rule files for architecture, frontend patterns, server actions, testing, git workflow and SDD workflow.

In the same example, the skill did not generate backend, database, i18n or forms rules, because the project had no NestJS, no ORM, hardcoded Spanish text and manual inputs. Styling was covered inside the frontend rules.

• Rules are only generated for areas the project actually uses.
• Results depend on what the skill finds in your files.