Creates, updates, or prunes an AGENTS.md for any repository by auditing the codebase, detecting non-discoverable gaps, and drafting minimal high-signal instructions. Triggers: AGENTS.md, agent setup, agent config, init agents, workspace setup, agent instructions, Claude setup. Uses: Read, Bash, Glob, Grep, AskUserQuestion. Outputs: AGENTS.md at repo root (or module-level for monorepos). Do NOT use for: writing README, generating docs, configuring CI, or editing code.
87
88%
Does it follow best practices?
Impact
78%
1.06xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the marks. It provides specific concrete actions, comprehensive trigger terms, clear 'what' and 'when' guidance, and explicit negative boundaries to prevent conflicts with similar skills. The inclusion of tools used and output location adds further precision.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'creates, updates, or prunes an AGENTS.md', 'auditing the codebase', 'detecting non-discoverable gaps', 'drafting minimal high-signal instructions'. Also specifies outputs and tools used. | 3 / 3 |
Completeness | Clearly answers 'what' (creates/updates/prunes AGENTS.md by auditing codebase and detecting gaps) and 'when' (explicit triggers list). Also includes negative boundaries ('Do NOT use for') which further clarifies scope. | 3 / 3 |
Trigger Term Quality | Includes a comprehensive explicit list of natural trigger terms: 'AGENTS.md, agent setup, agent config, init agents, workspace setup, agent instructions, Claude setup'. These cover common variations a user would naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinct niche focused specifically on AGENTS.md files. The explicit 'Do NOT use for' clause (README, docs, CI, code editing) actively prevents conflicts with adjacent skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, well-structured skill that provides highly actionable guidance for generating AGENTS.md files. Its greatest strengths are the concrete workflow with validation checkpoints, the detailed worked example, and the clear quality gate criteria. The main weaknesses are moderate verbosity from repeated emphasis on the same principles across sections, and references to bundle files that aren't provided for verification.
Suggestions
Reduce repetition by consolidating the discoverability filter messaging — it's stated in non-negotiables #2, #3, Phase 4 quality gate, the example's 'What is NOT included' note, and anti-patterns. State it once definitively and reference that statement.
Provide the referenced bundle files (./rules/audit-checklist.md and ./rules/discoverability-filter.md) or inline their essential content if they don't exist, since the skill delegates important details to them.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is generally well-written and avoids explaining basic concepts, but it's quite long (~200+ lines) with some repetition. The non-negotiables, process phases, and anti-patterns sections overlap in messaging (e.g., the discoverability filter is restated multiple times). The example section includes a disclaimer about tech stack details that itself adds verbosity. However, most content is genuinely instructive and non-obvious. | 2 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific file paths to scan, exact output format with markdown template, categorized gap types with examples, specific good/bad question examples for Phase 3, a complete worked example showing input through output, and explicit quality gate criteria. The process is copy-paste actionable with clear decision points. | 3 / 3 |
Workflow Clarity | The four-phase process is clearly sequenced with explicit validation checkpoints: Phase 4 includes a quality gate with three specific checks, requires user approval before writing, mandates diff summaries for updates, and includes a feedback loop ('Needs changes' / 'Start over' options). The conditional Phase 3 skip is well-defined. Destructive operations (overwriting existing AGENTS.md) have explicit safeguards (show diff, never blind-replace). | 3 / 3 |
Progressive Disclosure | The skill references two external files (./rules/audit-checklist.md and ./rules/discoverability-filter.md) which is good progressive disclosure design, but no bundle files are provided so we cannot verify these exist or are well-structured. The main file itself is quite long and could benefit from moving the detailed audit source table and gap classification table into referenced files. The structure within the file is well-organized with clear headings. | 2 / 3 |
Total | 10 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
a283f77
Table of Contents
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.