CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

bmad-project-context

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

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An exceptionally well-crafted instruction-only skill: executable commands with fallbacks, explicit approval gates around every write, and clean deferral of detail to two real one-level-deep references. The only flaw is redundancy in the ledger/deletion mechanics, which are explained more than once across sections.

DimensionReasoningScore

Conciseness

Dense imperative prose with no padding and no explanation of concepts Claude already knows; every paragraph carries workflow-specific decisions. Not 5 because there is noticeable redundancy — ledger and settling mechanics are restated across step 1, step 5, Adoption, and Audit, and the deletion-approval rules appear twice.

4 / 5

Actionability

For an instruction-only skill the guidance is fully executable: exact commands with arguments ('uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow', 'git log --diff-filter=DR --name-only'), fallback behavior for each failure mode, concrete interview limits ('Batches of at most eight; fewer is better'), and a worked example of a candidate line ('uv run pytest' where plain 'pytest' looks right).

5 / 5

Workflow Clarity

The multi-step process is clearly sequenced (activation steps 1-4, then steps 1-6, then Record/Audit variants) with explicit validation and approval checkpoints for the destructive operations: 'No writes until step 5!', 'Show the complete block before writing it', deletions 'held for line-item approval', and contradiction handling ('When the repo contradicts the user, show the evidence and ask') providing feedback loops.

5 / 5

Progressive Disclosure

Detail is appropriately split: block shape lives in references/template.md and admission grounds in references/best-practices.md — both verified to exist, one level deep, and loaded with explicit purpose ('Load references/best-practices.md and references/template.md before anything else', 'Compose against template.md', 'Deletion needs one of the four grounds in best-practices.md'). The body itself is well-sectioned and easy to navigate.

5 / 5

Total

19

/

20

Passed

Description

75%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific, in third person, and covers the full intent range of the skill with a real 'Use when' clause. Its main weakness is that the trigger guidance ('Use when invoked by name') is procedural rather than substantive — it never tells the user when they need this skill.

Suggestions

Replace or extend 'Use when invoked by name' with concrete trigger phrases, e.g. 'Use when asked to create, adopt, or audit a repo's AGENTS.md / agent instructions, or to record a mistake agents made'.

Add natural synonyms users might say — 'AGENTS.md', 'CLAUDE.md rules', 'repo instructions for agents', 'agent pitfalls' — to broaden trigger matching without adding vagueness.

State the concrete output ('a small verified block inside AGENTS.md, with provenance') so the 'what' covers what the skill actually produces, not just the verbs.

DimensionReasoningScore

Specificity

Names the domain ('a repository's agent instructions (the AGENTS.md block)') and lists several concrete actions covering all five operation modes ('Set up, adopt, refresh, or audit', 'records observed agent mistakes as pitfalls'). Falls short of 5 because the concrete outputs (verified block, ledger, provenance lines) are not stated, leaving minor coverage gaps.

4 / 5

Completeness

A clear 'what' (five operations on the AGENTS.md block plus pitfall recording) is paired with a 'when' clause ('Use when invoked by name'), so both are present. Not 5 because the 'when' is content-free — it names no concrete trigger phrases a user or harness could match against; not 3 because an explicit 'Use when...' clause does exist.

4 / 5

Trigger Term Quality

Contains good natural keywords for the niche: 'agent instructions', 'AGENTS.md', 'agent mistakes', 'pitfalls'. Not 3 because the terms present are the ones a user of this niche would actually say; not 5 because common synonyms and variations ('CLAUDE.md', 'repo rules', 'agent onboarding') are missing.

4 / 5

Distinctiveness Conflict Risk

A clear niche ('the AGENTS.md block', 'observed agent mistakes as pitfalls') with triggers unlikely to fire for unrelated skills. Minor overlap risk remains with instruction-generator skills like CLAUDE.md/init-type skills, which keeps it below 5.

4 / 5

Total

16

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

bmad-code-org/BMAD-METHOD

Path

skills/bmad-project-context/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.