agents-md

Use when reviewing, creating, shrinking, or refactoring AGENTS.md agent instructions, agent config files, routing rules, or repository guidance that need scoped routing, dedupe, contradiction fixes, progressive disclosure, and cleaned instruction surfaces.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

70%

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

The content is a well-structured, validation-heavy runbook with clear sequencing and properly deferred detail. It could be tightened in prose and made more copy-paste executable, but it assumes Claude's competence and avoids concept padding.

Suggestions

Tighten jargon-heavy phrases like 'bounded instruction-provenance inventory' and 'canonical-source versus projection parity' into plainer wording to improve conciseness.

Add one or two concrete, copy-paste-ready command snippets (e.g., the exact rg invocation and expected output shape) to lift actionability toward executable guidance.

Provide a short worked example of a Context ledger entry so the procedure is immediately reproducible rather than abstractly described.

Dimension	Reasoning	Score
Conciseness	The body is largely free of concept-explaining padding and earns most of its tokens, but dense jargon ('bounded instruction-provenance inventory', 'canonical-source versus projection parity') could be tightened, keeping it below the lean anchor.	2 / 3
Actionability	Concrete commands appear ('rg --files', 'rg -n "(command\|path\|handle)" .') and steps are specific, but most guidance is procedural prose rather than copy-paste-ready executable examples, fitting the 'some concrete guidance but incomplete' anchor.	2 / 3
Workflow Clarity	A 14-step sequenced workflow with explicit validation checkpoints and feedback loops ('fix the first failure class and rerun the same gate'), plus destructive-contract safeguards, matches the clear-sequence anchor.	3 / 3
Progressive Disclosure	The body is an overview that signals one-level-deep references to real files ('references/agents-md-guidance.md', 'references/discovery-interview.md') and gates scripts/assets by need, with well-organized sections and easy navigation.	3 / 3
	Total	10 / 12 Passed

Description

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.

The description is specific, uses natural trigger phrasing, and explicitly covers both what the skill does and when to use it, with a clear niche. It is concise without padding or over-claims.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('reviewing, creating, shrinking, or refactoring AGENTS.md') plus specific operations ('scoped routing, dedupe, contradiction fixes, progressive disclosure'), matching the 'lists multiple specific concrete actions' anchor.	3 / 3
Completeness	Explicit 'Use when...' clause states when to invoke it and the preceding verbs state what it does, satisfying both what and when.	3 / 3
Trigger Term Quality	Natural terms a user would say ('AGENTS.md', 'agent instructions', 'agent config files', 'routing rules', 'repository guidance') give good coverage of phrasings users actually use.	3 / 3
Distinctiveness Conflict Risk	Scoped tightly to AGENTS.md and instruction surfaces with distinct triggers, making conflict with unrelated skills unlikely.	3 / 3
	Total	12 / 12 Passed

Validation

93%

Warnings & errors only

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

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_field	'metadata' should map string keys to string values	Warning

	Total	15 / 16 Passed

Repository: jscraik/Agent-Skills
Path: Skills/agent-ops/agents-md/SKILL.md
Commit: 4f7075e

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

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.