agents-md

Create and maintain AGENTS.md documentation for simple projects, complex monorepos, deterministic discovery, scoped instruction files, low-token navigation; use when generating AGENTS.md, updating agent docs, standardizing AI-facing project guidance.

Quality

78%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/agentic-harness/agents-md/SKILL.md

Quality

Content

78%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, actionable skill body: concrete discovery and verification commands, a clear 5-step workflow with validation, and exemplary one-level-deep progressive disclosure across real reference files. The residual gaps are minor — slight redundancy between Principles/Anti-Patterns sections and the reference files, and no explicit error-recovery loop after verification.

Suggestions

Add a short feedback loop after Verification (e.g., "If markdownlint fails, fix the flagged lines and re-run; see references/troubleshooting.md") to close the error-recovery gap.

Trim the inline Anti-Patterns section to the rule statements and push the WHY/BAD/GOOD detail into references/anti-patterns.md, which already covers it, reducing duplication with the body.

Dimension	Reasoning	Score
Conciseness	The body is lean with terse WHY/BAD/GOOD one-liners and no padding explaining concepts Claude already knows. It falls short of 5 because the "Principles" section partially restates later sections and the four inline anti-patterns duplicate content in references/anti-patterns.md, which could be trimmed.	4 / 5
Actionability	Provides copy-paste-ready commands ("rg --files", "rg -n \"workspaces\|nx\|turbo...\"", "find . -name AGENTS.md", "bunx markdownlint-cli2 \"**/AGENTS.md\"\") and a concrete minimal template. Minor gaps keep it at 4 rather than 5: no inline example of a monorepo root file linking to scoped sub-files, and the template contains a placeholder.	4 / 5
Workflow Clarity	The 5-step workflow has explicit per-step outputs and a validation checkpoint ("Validate command correctness and duplication boundaries") plus a Verification section with commands. It is not 5 because there is no error-recovery feedback loop (e.g., what to do when markdownlint fails is only handled indirectly in references/troubleshooting.md).	4 / 5
Progressive Disclosure	A concise overview with a well-labeled References table covering seven topics; all seven referenced files exist in references/ and are one level deep with no nested references. Content is appropriately split (templates and detailed anti-patterns pushed to reference files), matching the top anchor.	5 / 5
	Total	17 / 20 Passed

Description

78%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 description with an explicit "use when" clause, concrete trigger phrases, and a clearly staked-out AGENTS.md niche. Its main weakness is specificity: beyond "create and maintain", the capability list dissolves into attribute noun phrases rather than concrete actions.

Suggestions

Rewrite the middle of the description as verbs (e.g., "Discover repo shape, generate root and scoped subdirectory AGENTS.md files, keep instructions low-token and deduplicated") instead of attribute noun phrases like "deterministic discovery, scoped instruction files, low-token navigation".

Add natural trigger synonyms users might say, such as "agent instructions", "CLAUDE.md", or "project documentation for AI agents", to broaden keyword coverage.

Dimension	Reasoning	Score
Specificity	"Create and maintain" are the only concrete verbs; the middle list ("deterministic discovery, scoped instruction files, low-token navigation") is attribute noun phrases rather than actions, matching the anchor for domain plus 1-2 concrete actions but not comprehensive. A 4 would require several specific listed actions, which this does not have.	3 / 5
Completeness	It clearly answers "what" ("Create and maintain AGENTS.md documentation for simple projects, complex monorepos") and explicitly answers "when" with concrete trigger phrases ("use when generating AGENTS.md, updating agent docs, standardizing AI-facing project guidance"). This matches the top anchor rather than 4, whose "when" clause is generic.	5 / 5
Trigger Term Quality	"use when generating AGENTS.md, updating agent docs, standardizing AI-facing project guidance" includes the key natural term users would say, but common variations like "agent instructions", "CLAUDE.md", or "project documentation" are missing. Good coverage with a few natural terms absent matches this anchor; not 5 because synonyms/extensions are incomplete, not 3 because the core triggers are strong.	4 / 5
Distinctiveness Conflict Risk	The AGENTS.md niche is distinct with clear triggers, but "agent docs" and "AI-facing project guidance" create minor overlap risk with general documentation or project-init skills. Mostly distinct with minor overlap matches this anchor; not 5 because the broader phrasing is not fully unambiguous.	4 / 5
	Total	16 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: pantheon-org/tekhne
Path: skills/agentic-harness/agents-md/SKILL.md
Commit: a1083f4

Reviewed: 12 minutes 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.