Guide · Agent skill
How to use the Generate AI Agent Instructions skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains what the acreadiness-generate-instructions agent skill does, how to install it, and how to ask your agent to use it. It is for developers who want AI coding assistants such as Copilot in VS Code to follow their repository's conventions. By the end you will know how to preview the generated instruction files, choose a flat or nested layout, and review the output before it steers future changes.
Generate AI Agent Instructionsgithub/awesome-copilot · MIT Download the skill Quick start
- 1Install the skill. Download the ZIP from the skill page and unzip it into ~/.claude/skills/ for personal use or the project's .claude/skills/ folder. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Check prerequisites. Confirm Node.js with npx is available and that you have model access for generation. Add agentrc.config.json if you need monorepo area files.
- 3Run the assessment first. Run /acreadiness-assess so the skill has readiness gaps in the AI Tooling pillar to address.
- 4Ask for generation and choose a strategy. Tell the agent what you want, and choose flat or nested when asked. Flat is the default.
- 5Preview with a dry run. The agent runs the AgentRC instructions command with --dry-run and summarises which files would be created or overwritten, plus the model and any applyTo globs.
- 6Review and confirm. Read the generated files and the applyTo globs, then confirm the real run. Commit only after you have reviewed the content.
What the skill makes the agent do
When this skill is installed, the agent knows how to create, regenerate, or refresh custom instruction files that tell AI coding assistants how your project works. It does this by running the AgentRC tool through npx, and it usually starts with a dry-run preview so you can see what would change.
The skill is designed as the follow-up step after an accessibility-style readiness assessment of your AI Tooling setup. Its source describes it as the step that closes gaps in the AI Tooling pillar, after you have run /acreadiness-assess.
- Creates or refreshes .github/copilot-instructions.md, the default file for Copilot in VS Code.
- Can write AGENTS.md instead, for repositories used by several agents such as Copilot, Claude, and Cursor.
- Can split guidance into a main file plus scoped .instructions.md files for specific folders or topics.
Install the skill
The skill ships as a folder whose main file is SKILL.md. You can install it in one of two ways: download the ZIP from the skill's page and unzip it, or upload it in the Claude apps.
For a personal install, unzip the skill into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. In the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your repository
- Claude apps: Settings → Capabilities → Skills
Check the requirements before you run it
The skill depends on the AgentRC tool, which is fetched at run time with npx, so you need Node.js with npx available. The skill's source uses the package reference github:microsoft/agentrc.
Generation uses a model. The default model is claude-sonnet-4.6, which means you need model access, usually through an account or API credentials for the model service. If you want per-area files for a monorepo, you also need an agentrc.config.json file that declares your areas and their paths.
- Node.js with npx available
- AgentRC, fetched automatically via npx -y github:microsoft/agentrc
- Model access for generation (default model claude-sonnet-4.6)
- An agentrc.config.json file, only needed for monorepo area features
Trigger the skill with a natural request
You do not need to memorise flags. Ask in plain language, for example that you want to create or refresh your Copilot instructions. The skill's slash name is /acreadiness-generate-instructions, and it accepts optional arguments such as --output, --strategy, --areas, --area, --apply-to, --claude-md, and --dry-run.
The agent will normally ask which strategy you want, flat or nested, unless you already said so. It will then run a dry run and show a short summary before writing anything.
- "Generate Copilot instructions for this repo."
- "Refresh my AI agent instructions after the readiness assessment."
- "Create per-area instruction files for the frontend and API folders in this monorepo."
- "Make an AGENTS.md shared by Copilot and Claude."
npx -y github:microsoft/agentrc instructions --output <file> --strategy <flat|nested> [--areas|--area <name>] [--claude-md] --dry-runChoose flat or nested and understand the output
Flat is the default. It writes one file at the chosen path, which is simple and easy to review in a single pull request. Nested writes a hub file at .github/copilot-instructions.md plus per-topic files in .github/instructions/, each with an applyTo glob so VS Code loads a topic only when it is relevant.
When the main output is .github/copilot-instructions.md, the skill moves AgentRC's nested topic files into .github/instructions/ and adds applyTo frontmatter. If you chose --output AGENTS.md, nested keeps AgentRC's default .agents/ layout.
- Flat: one file, best for small or medium repos with one stack.
- Nested: hub plus topic files, best for large or multi-stack repos.
- The skill recommends nested when the repo has more than five top-level directories, several stacks, or a monorepo tool such as turbo, nx, or pnpm workspaces.
- Add --claude-md with nested to also emit CLAUDE.md.
Use area files with applyTo for monorepos
For a monorepo, the skill can write one file per declared area at .github/instructions/<area>.instructions.md. Each file starts with frontmatter that names the glob its rules apply to, taken from the area's paths in agentrc.config.json. If an area has no paths, the skill asks you for a glob.
The root .github/copilot-instructions.md stays as the always-on file. Area files only apply to matching paths.
- Example glob: apps/frontend/** for a frontend area.
- Use --apply-to to set the glob on a single-area run.
- File names are lowercase kebab-case, such as frontend.instructions.md or api.instructions.md.
---
applyTo: "apps/frontend/**"
---Safety notes before you commit
This skill runs scripts and uses the network. It fetches AgentRC with npx, and generation sends code context to a model service, with the default model being hosted. Check that this is allowed for your project before you run it, especially for sensitive or regulated code.
The output directly steers how future AI code changes are made, so read the generated files before committing them. The skill writes files in your repository, and it can overwrite existing ones unless you stop and review the dry-run summary. The --force option is used only when files already exist and you have confirmed the overwrite.
- Always review the dry-run summary before confirming.
- Read every generated file, including applyTo globs, before committing.
- Do not use it where generated rules cannot be reviewed or where sending code to a model service needs approval.
What people use it for
- Make Copilot in VS Code follow a repository's coding conventions by generating .github/copilot-instructions.md.
- Give a monorepo's frontend, API, and infrastructure folders different rules using per-area .instructions.md files with applyTo globs.
- Create a shared AGENTS.md for a team that uses Copilot, Claude, and Cursor together.
- Refresh existing instructions after changing the project's stack, then re-run the assessment to check the AI Tooling score.
Frequently asked questions
Is the Generate AI Agent Instructions skill free to use?
The skill is published under the MIT licence, as listed on its page. Generation uses a model through AgentRC, and the default model is hosted, so you need model access through an account or API credentials. Check the model service's terms for any costs, since this guide does not state prices.
What do I need to install the acreadiness-generate-instructions skill?
You need the skill folder with its SKILL.md file, placed in ~/.claude/skills/ or a project's .claude/skills/ folder, or uploaded in the Claude apps under Settings → Capabilities → Skills. To run it, you also need Node.js with npx and access to a model for AgentRC.
Does this skill work without the AgentRC tool?
No. The skill depends on AgentRC, which it runs via npx from github:microsoft/agentrc. If you cannot run that tool, the skill cannot generate the files.
Where does the skill save the instruction files?
By default it writes .github/copilot-instructions.md, which is the native file for Copilot in VS Code. With nested output it adds topic or area files in .github/instructions/, and with --output AGENTS.md it can write AGENTS.md for multi-agent repositories.
Can I preview the changes before the skill writes anything?
Yes. The skill is designed to run a dry run first using --dry-run, then show a summary of files that would be created or overwritten. It only runs the real command after you confirm.
What should I do if generated files already exist?
The skill's flags include --force, which the agent can use when files already exist. Before using it, review the dry-run summary to see what would be overwritten, and keep a copy of any file you want to keep.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you want Copilot in VS Code, or several AI agents, to follow your repository's conventions, and you are comfortable running npx tools and sending code to a model service. Pick something else, or write your instructions by hand, if you cannot review generated rules before committing or your project does not allow code to go to a model service.
Download the skill