agents-md

Use when reviewing, creating, shrinking, or refactoring AGENTS.md and directly linked instruction guidance that need scoped routing, deduplication, contradiction resolution, or progressive disclosure.

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Failed to scan

The risk profile of this skill

Quality

Content

77%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.

A well-structured runbook with explicit validation, feedback loops, and clean progressive disclosure to real reference files. Its main weakness is dense, jargon-heavy prose that could be tightened for token efficiency.

Suggestions

Tighten compound noun phrases (e.g., "canonical-source versus projection parity" → "canonical-source and projection match") to reduce token load without losing meaning.

Replace abstract step phrasing in the Workflow with the concrete command or artifact each step produces, so every step is unambiguously executable.

Move the long Condition-led clauses in the Outputs and Workflow sentences into short bullet form to cut redundant connective tissue.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining concepts Claude already knows, but it is densely packed with over-stuffed compound noun phrases ("canonical-source versus projection parity," "verified Context Pointer map") that could be tightened without losing meaning, landing it just above the midpoint rather than lean.	3 / 5
Actionability	Concrete executable guidance is present — specific commands like `rg --files` and `rg -n "(command\|path\|handle)" .`, real reference file paths, and decision tokens (`no_justified_edit`, `Decision required:`) — with only minor gaps where steps stay abstract.	4 / 5
Workflow Clarity	A clear 14-step sequence is paired with explicit validation checkpoints (steps 8 and 14, a Validation section) and a feedback loop ("If validation fails, fix the first failure class and rerun the same gate before broadening"), satisfying the anchor for explicit validation and error recovery.	5 / 5
Progressive Disclosure	The overview points to one-level-deep, well-signaled references — `references/agents-md-guidance.md` and `references/discovery-interview.md`, both real files — with detailed routing categories kept in the reference rather than inlined, and the References section states when each should be loaded.	5 / 5
	Total	17 / 20 Passed

Description

87%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.

A strong, specific description that names a distinct niche and provides an explicit Use-when trigger fusing what and when. Its only weakness is moderate reliance on abstract jargon over natural synonyms.

Dimension	Reasoning	Score
Specificity	Names the domain (AGENTS.md) and several concrete actions — "reviewing, creating, shrinking, or refactoring" — plus "scoped routing, deduplication, contradiction resolution, or progressive disclosure," but the verbs remain broad categories rather than granular operations, so it stops short of comprehensive coverage.	4 / 5
Completeness	The opening "Use when reviewing, creating, shrinking, or refactoring AGENTS.md..." explicitly fuses a concrete "what" with an explicit "when" trigger clause, answering both clearly.	5 / 5
Trigger Term Quality	Natural user phrases like "refactor AGENTS.md," "shrink," and "review" appear, but it leans on technical jargon ("scoped routing," "progressive disclosure") and omits common synonyms such as "audit," "clean up," or "simplify."	4 / 5
Distinctiveness Conflict Risk	The skill is scoped to AGENTS.md and directly linked instruction guidance — a narrow, clearly named niche with distinct triggers and minimal overlap with other skills.	5 / 5
	Total	18 / 20 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: 2f91362

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.