agents-md
Use when reviewing, creating, shrinking, or refactoring AGENTS.md instruction surfaces that need scoped routing, dedupe, contradiction fixes, or progressive disclosure.
59
68%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./Skills/agent-ops/agents-md/SKILL.mdQuality
Discovery
75%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 has strong completeness with an explicit 'Use when...' clause and is highly distinctive in its niche around AGENTS.md instruction surfaces. However, it relies on domain-specific jargon that may not match how all users naturally phrase their requests, and the specific actions could be more concretely described in terms of outputs or deliverables.
Suggestions
Add more natural language trigger terms such as 'agent instructions', 'agent config file', or 'agent routing rules' to improve discoverability for users who may not use the exact jargon.
Clarify the concrete outputs or transformations (e.g., 'produces cleaned, deduplicated AGENTS.md files with clear routing rules') to improve specificity beyond listing abstract operations.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names several actions (reviewing, creating, shrinking, refactoring) and domain-specific concepts (scoped routing, dedupe, contradiction fixes, progressive disclosure), but these are somewhat jargon-heavy and don't clearly explain what concrete outputs or transformations are produced. | 2 / 3 |
Completeness | The description explicitly addresses both 'what' (reviewing, creating, shrinking, refactoring AGENTS.md instruction surfaces with scoped routing, dedupe, contradiction fixes, progressive disclosure) and 'when' (opens with 'Use when...' providing clear trigger conditions). | 3 / 3 |
Trigger Term Quality | It includes some relevant terms like 'AGENTS.md', 'refactoring', 'dedupe', and 'contradiction fixes' that a knowledgeable user might say, but misses more natural/common variations a typical user would use (e.g., 'agent instructions', 'agent config', 'instruction file'). The terms 'scoped routing' and 'progressive disclosure' are fairly technical jargon. | 2 / 3 |
Distinctiveness Conflict Risk | The description is highly specific to AGENTS.md files and their particular concerns (scoped routing, dedupe, contradiction fixes, progressive disclosure), making it very unlikely to conflict with other skills. This is a clear, distinct niche. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
62%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-structured instruction skill with strong workflow clarity and explicit validation/failure handling, making it effective for its complex domain of AGENTS.md management. However, it suffers from internal redundancy across sections (Avoid/Anti-Patterns, Constraints/Failure Mode) that inflates token cost, and it lacks concrete executable examples or templates that would make it more immediately actionable. The progressive disclosure references are well-conditioned but unverifiable without bundle files.
Suggestions
Consolidate overlapping sections: merge 'Avoid' into 'Anti-Patterns', and deduplicate preservation-contract rules that appear in Workflow step 5, Constraints, and Failure Mode into a single authoritative location with back-references.
Add at least one concrete input/output example showing a before/after AGENTS.md edit with the context ledger, Context Pointer map, and labeled output format, rather than only describing scenarios in prose.
Include a minimal schema or template for the 'schema_version' output mentioned in Outputs, so Claude knows the exact structure expected.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but contains significant repetition—anti-patterns restate constraints and avoid sections, failure modes repeat preservation rules multiple times, and several sections overlap (e.g., 'Avoid' vs 'Anti-Patterns', 'Constraints' vs 'Failure Mode'). Some content could be consolidated without losing clarity. | 2 / 3 |
Actionability | The skill provides structured guidance with specific labels ('Decision required:', 'Preservation rule:') and concrete examples of contradiction scenarios, but lacks executable code/commands. The workflow steps are procedural but abstract—no actual command examples, no template snippets, no schema examples for schema_version outputs. The examples section describes scenarios rather than showing input/output pairs. | 2 / 3 |
Workflow Clarity | The 10-step workflow is clearly sequenced with explicit validation checkpoints (step 4: stop on contradictions, step 5: classify before deleting, step 10: validate). Failure modes include feedback loops (fix first failure, rerun gate). The 'fail fast' pattern is reinforced in both Constraints and Validation sections, and the skill handles error recovery paths well. | 3 / 3 |
Progressive Disclosure | The skill references external files like 'references/agents-md-guidance.md' and 'Plugins/harness-engineering/skills/he-plan/SKILL.md' with clear conditions for when to load them, which is good. However, no bundle files were provided to verify these references exist, and the SKILL.md itself is quite long (~130 lines) with content that could be split—e.g., the anti-patterns, gotchas, and failure modes sections could be in a reference doc given their length and overlap with other sections. | 2 / 3 |
Total | 9 / 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 | |
- Repository
- jscraik/Agent-Skills
- Commit
435084b
- 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.