bmad-project-context Skill: Set Up and Maintain Your Repo's AGENTS.md

Builds, refreshes and audits a small verified block of agent instructions inside your repo's AGENTS.md, and records agent mistakes as pitfalls.

Installs: 12.8K; on skills.sh
Stars: 54.9K; on GitHub
Files: 4; besides SKILL.md
Updated: Nov 2026; last repo commit

bmad-project-context is a BMad Method skill for the AGENTS.md file in your repository. In a conversation, Claude combines the rules you bring with what the repo itself confirms, and writes a short block between markers. Its intents are setup, adopt, refresh, record and audit. SKILL.md says it is conversational and you approve every write.

It writes only a block that you have seen in full, along with a ledger showing where each existing instruction went. It never commits. It is invoked by name. Its first step runs a uv run script from _bmad/scripts, and if that script is missing it offers the bmad setup.

Good for

Maintainers whose AGENTS.md is missing, bloated or out of date
Teams that want agent rules checked against the repo's real commands and paths
Developers who keep re-telling agents the same correction
Anyone moving a CLAUDE.md into a cleaner AGENTS.md

Install bmad-project-context

Claude Code

Copy this prompt.

Install the bmad-project-context skill in Claude Code. Run this command:

npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-method --skill bmad-project-context

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js, Git, uv.

bmad-project-context belongs to the bmod-method module and needs the bmad skill, which sets up the _bmad folder in your project. The README needs uv for BMad setup and Python scripts. These are the v7 preview alpha skills from the main branch, which the README says change often. There is no Claude app upload route, because the skill runs uv scripts inside a project folder. The plugin marketplace repo lists the plugins as bmad-method and bmad-toolbox, while the main README calls the second one bmad-core-tools. The plugin tree holds skills only, with no hooks or MCP files.

Built from the package data we hold. Not yet tested by us.

What's in the skill

When it loads

Set up, adopt, refresh, or audit a repository's agent instructions (the AGENTS.md block) so AI agents work well in that repo. Also records observed agent mistakes as pitfalls. Use when invoked by name

Sections in SKILL.md

Resolution rules
On Activation
Setup, Adoption, and Refresh Steps
1. Assess and report
2. Ask what they bring
3. Discover and verify
4. Interview the gaps
5. Show the block, then write it
6. Close
Refresh
Adoption
Greenfield
Migration
Record
Audit
Children

Key facts

Author: BMad Code (bmad-code-org)
Repository: bmad-code-org/bmad-method
Installs on skills.sh: 12,801 as of 2026-11-02
GitHub stars: 54,859 for the whole repo, 2026-11-02
Last commit to the repo: 2026-11-01
Files: 5 files including SKILL.md (references/best-practices.md, references/template.md, bmod.toml, customize.toml)
License: MIT per the repo LICENSE file and README (GitHub license detection reports NOASSERTION)
Module: Part of bmod-method; needs the bmad skill and uv
Status: README calls these v7 skills a preview alpha
Writes: A managed block in AGENTS.md between  markers

What it includes

Creates the block when no instruction file has meaningful content
Claude reads the repo, asks what rules you bring, scans config, CI and source in parallel subagents, interviews you on gaps, shows the block and writes it after approval.
Try: “Use bmad-project-context to set up agent instructions for this repo.”
Write · setup
Takes an existing instruction file with no managed block
The existing file is the baseline. Every instruction enters a ledger with a decision (retain, rewrite, relocate, automate or delete) and a reason, and deletions need one of four grounds from best-practices.md.
Write · adopt
Re-verifies a managed block against the repo since the recorded SHA
Reads the provenance line, re-checks paths and caveats, and runs git log --diff-filter=DR --name-only since the recorded SHA. Proposed removals are shown, never silent.
Runs code · refresh
Captures one observed agent mistake as a pitfall or exact command
A recurring or costly mistake earns a line. If a hook, lint rule or CI check could prevent it, Claude proposes that instead.
Write · record
Re-checks every caveat and path and prunes failing lines
The audit ends smaller or equal. A policy or pitfall is removed only when the thing it guards is gone or you retire it.
Write · audit
Orientation, Policy, Where things are, Running and verifying, Conventions, Pitfalls
Terse imperative lines under six headings. Claude omits empty sections and leaves out what package.json, a Makefile or CI config already say.
Block template
Optional separate rules files for substantial subtrees, with your approval
A child file is created only when its rules are subtree-exclusive and substantial, loading is verified for every harness in use, and you approve the split.
Children

From the official docs

Permissions

Medium risk

The skill reads your repo and git history and rewrites your AGENTS.md block after you approve it. Review the ledger and the diff before committing.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can remove existing instruction lines
In adopt and refresh the ledger can mark lines for deletion or relocation. Read the ledger before approving, and keep AGENTS.md in git. github.com
It scans your repo and history
It fans out subagents over config, source and git history, including git log with --diff-filter=DR. Point it at a repo you are comfortable sharing with your AI tool. github.com
Extra source paths or URLs are read
You can pass additional source paths or URLs, and it asks for outside documents such as wikis. Only share what you want in the conversation. github.com

Technical details

Scopes	Reads AGENTS.md, rule files, docs, CI and config, source and git history Edits AGENTS.md between its markers after you approve the block May propose edits to other instruction files such as CLAUDE.md Runs uv run scripts from _bmad/scripts when that folder exists

Questions

What does bmad-project-context do?

It sets up, adopts, refreshes, records pitfalls into and audits a small block of agent instructions in your repo's AGENTS.md.

How do I install it in Claude Code or Codex?

Use the install box at the top of this page. It installs the skill with the bmad hub skill and its module record. Then ask bmad to run bmad setup in your project.

Does it need the rest of BMad?

It needs the bmad skill and uv. Its first step runs a script from _bmad/scripts and offers the BMad setup if the script is missing. The config step is skipped when no _bmad folder exists.

Does it edit my CLAUDE.md or other instruction files?

Only through a ledger entry or a fix you have seen. It may propose fixes where an instruction elsewhere contradicts the block, for example a stale CLAUDE.md line.

Is it safe?

It reads your repo and git history, and edits AGENTS.md only after you approve the full block and ledger. SKILL.md says it never commits, but check the diff before you do.

Does it delete my existing instructions?

Only with a reason from best-practices.md that you have seen. A deletion that rests on none of the first three grounds needs your line-item approval.

Does it work in the Claude app?

The install box leaves out a Claude app upload route, because the skill reads and edits files in your repository. Use Claude Code, Codex or another coding tool that supports skills.

Information

updated Nov 2, 2026

Repository: bmad-code-org/bmad-method
Folder: skills/bmad-project-context

bmad-code-org/bmad-method skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

BMAD-METHOD README · github.com
bmad-plugins README · github.com
bmad-plugins marketplace.json · github.com
bmad-project-context SKILL.md · github.com
best-practices.md · github.com
template.md · github.com