CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

writing-for-agents

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is writing-for-agents in slurpyb/pi-taskfile

SKILL.md
Quality
Evals
Security

Quality

Content

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

An exceptionally well-crafted reference skill: dense, assumption-of-competence prose that pairs every lever with a concrete test, failure mode, and cure, and correctly pushes skill-specific mechanics behind a one-level pointer. The only deductions are the absence of an overarching ordered procedure across its levers and the unverifiable SKILL-MECHANICS.md reference in the provided bundle.

DimensionReasoningScore

Conciseness

The body is dense reference prose with no padding and no explanations of things Claude already knows: every section delivers a named lever ("context pointer", "information hierarchy", "leading word", "no-op"), its failure mode, and its cure, assuming the model's competence throughout (e.g. "The test (does it change behaviour versus the default?) is model-relative"). It matches anchor 5 ('lean and efficient; assumes Claude's competence; every token earns its place') rather than 4, because there is no over-explanatory passage that could simply be trimmed — even the illustrative asides ("_Don't think of an elephant_...") are single-sentence and carry the point they illustrate.

5 / 5

Actionability

For an instruction-only skill the guidance is concrete and testable throughout: explicit tests ("the document should read like documentation written for the agent"; the branch test "inline what every branch needs, and push behind a pointer what only some branches reach"; the no-op test "does it change behaviour versus the default?"), ordered procedures ("Defend in order: sharpen the bound first (local and cheap); only if it is irreducibly fuzzy... hide the later steps"), and worked rewrite examples ("'fast, deterministic, low-overhead' → _tight_", with the positive-phrasing alternative "write one-line comments"). This matches anchor 5's 'specific examples cover the common cases'; it is not 4 because there is no gap where guidance stays high-level without a concrete test or example.

5 / 5

Workflow Clarity

The skill is all-reference by design ("all reference (a review's rules, this skill)"), so there is no multi-step workflow to sequence, and no destructive or batch operations that would require validation checkpoints or impose a cap. The one procedural path present is explicitly ordered (sharpen the bound first, then split only if the rush is observed; sharpen the pointer wording first, inline only if sharpening fails), matching anchor 4's 'clear sequence with most checkpoints present' territory rather than 5, because the reference provides no overarching decision procedure ordering its many levers for a run (which lever to check first when auditing a document), and no verification checkpoint for the writer (e.g. a final pass or self-check).

4 / 5

Progressive Disclosure

Structure is good: eight well-scoped headings, and skill-specific mechanics are appropriately split out behind a clearly signaled, one-level-deep pointer ("When the document you're writing is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills"), keeping the body general. This sits at anchor 4 rather than 5 because the referenced SKILL-MECHANICS.md could not be verified in the provided bundle (no references/, scripts/, or assets/ directories and no SKILL-MECHANICS.md file exist alongside SKILL.md), so the split's other side cannot be confirmed — a minor organization gap rather than the fully verified, well-signaled split of the 5-anchor.

4 / 5

Total

18

/

20

Passed

Description

70%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 concise, third-person description with an explicit and concrete 'Use when' clause anchored on specific filenames (AGENTS.md, CLAUDE.md, skills). Its main weakness is the thin 'what' — it names the domain but not the concrete levers the reference teaches, and it lacks natural synonym coverage like 'instructions' or 'agent docs'.

Suggestions

Expand the what-clause to name the concrete capabilities, e.g. 'Structuring skills, AGENTS.md/CLAUDE.md, and other agent-consumed documents for predictability: progressive disclosure, context pointers, pruning, leading words. Use when...'

Add natural trigger synonyms users would say, such as 'instructions', 'agent guidelines', or 'prompts', alongside the existing skill/AGENTS.md/CLAUDE.md triggers.

DimensionReasoningScore

Specificity

"Writing documents for agents" names the domain and the core action, and the when-clause names concrete artifacts ("creating or editing skills, or modifying AGENTS.md or CLAUDE.md"), but the what-clause lists no concrete capabilities of the reference itself (progressive disclosure, pruning, leading words are all absent). It matches the anchor 'Names domain and 1-2 concrete actions, but not comprehensive' rather than 2, because the named artifacts go beyond a bare verb-plus-object like 'Processes PDF files'; it is not 4 because no several specific actions are listed.

3 / 5

Completeness

Both parts are present: what ("Writing documents for agents") and an explicit when with concrete triggers ("Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md"). It sits between anchors 4 and 5 — the when-clause is fully explicit, but the what is terse and does not convey what the reference actually provides (structuring documents so agents consume them predictably), so the 'what' could be more informative as the 4-anchor describes.

4 / 5

Trigger Term Quality

Natural terms users would say are present — "skills", "creating", "editing", "AGENTS.md", "CLAUDE.md", "modifying" — which are strong, file-name-level triggers. It falls short of anchor 5 because common variations are missing: "instructions", "agent docs", "prompts", "documentation", "memory" files, or equivalents of the '.pdf'-style extension coverage.

4 / 5

Distinctiveness Conflict Risk

Naming AGENTS.md and CLAUDE.md explicitly gives clear, distinct triggers with minimal conflict risk against unrelated skills. Minor overlap remains with closely related skills (general documentation-writing or CLAUDE.md-generation skills like an init skill), matching anchor 4 rather than 5's 'clear niche with no overlap'.

4 / 5

Total

15

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 2 missing

Warning

Total

15

/

16

Passed

Repository

slurpyb/pi-taskfile

Path

.agents/references/agent/ref.SnsMf8Zb/SKILL.md

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.