Creates, updates, or optimizes an AGENTS.md file for a repository with minimal, high-signal instructions covering non-discoverable coding conventions, tooling quirks, workflow preferences, and project-specific rules that agents cannot infer from reading the codebase. Use when setting up agent instructions or Claude configuration for a new repository, when an existing AGENTS.md is too long, generic, or stale, when agents repeatedly make avoidable mistakes, or when repository workflows have changed and the agent configuration needs pruning. Applies a discoverability filter—omitting anything Claude can learn from README, code, config, or directory structure—and a quality gate to verify each line remains accurate and operationally significant.
95
95%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
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 clearly articulates specific capabilities, provides explicit trigger conditions via a 'Use when...' clause with multiple scenarios, and occupies a distinct niche around AGENTS.md file management. It uses proper third-person voice throughout and balances detail with conciseness, making it easy for Claude to select appropriately from a large skill set.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Creates, updates, or optimizes an AGENTS.md file', 'covering non-discoverable coding conventions, tooling quirks, workflow preferences, and project-specific rules', 'Applies a discoverability filter', 'a quality gate to verify each line remains accurate and operationally significant'. These are detailed, concrete capabilities. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates/updates/optimizes AGENTS.md with specific filtering and quality gates) and 'when' with an explicit 'Use when...' clause listing four distinct trigger scenarios: new repo setup, existing AGENTS.md problems, repeated agent mistakes, and changed workflows. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'AGENTS.md', 'agent instructions', 'Claude configuration', 'repository', 'too long', 'generic', 'stale', 'avoidable mistakes', 'agent configuration', 'pruning'. These cover a good range of natural phrasings a user might use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — targets a very specific artifact (AGENTS.md) with a clear niche around agent configuration files. The mention of discoverability filtering and quality gates further distinguishes it from generic documentation or configuration skills. Unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted, concise skill that clearly communicates the philosophy and process for creating effective AGENTS.md files. Its strongest aspects are the discoverability filter as a decision framework and the quality gate as a validation step. The main weakness is the lack of concrete, executable examples—a sample AGENTS.md snippet showing good vs. bad entries would significantly improve actionability.
Suggestions
Add a concrete before/after example showing a verbose AGENTS.md entry transformed into a lean, non-discoverable one (e.g., 'Before: "This project uses TypeScript with React" → Remove: discoverable from package.json')
Include a short sample AGENTS.md output (3-5 lines) demonstrating the recommended format and tone for entries
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section earns its place. No unnecessary explanations of what AGENTS.md is or how agents work. The content is lean, with clear decision criteria and concrete examples. No padding or redundant context. | 3 / 3 |
Actionability | The guidance is specific and well-structured with clear decision criteria (discoverability filter, quality gate), but lacks concrete executable examples—no sample AGENTS.md output, no before/after comparison, no template showing what a good entry looks like versus a bad one. The 'typical examples' are parenthetical descriptions rather than copy-paste-ready content. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced: check source files first → apply discoverability filter → write/update with recommended structure → run quality gate before finalizing. The quality gate serves as an explicit validation checkpoint with three specific checks, and the maintenance mindset section provides a feedback loop for ongoing improvement. | 3 / 3 |
Progressive Disclosure | For a skill of this size (~80 lines), the content is well-organized into clearly labeled sections with logical progression from 'when to use' through core rules, inclusion/exclusion criteria, structure recommendations, source files, maintenance, and quality gate. No external references are needed and none are artificially created. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents