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

65%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/references/agent/ref.rL4A1ZHm/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

46%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-organized, intellectually dense reference whose conceptual material is largely original (not recycled knowledge), but it operates almost entirely at the abstraction level: few concrete tests, no applied workflow, and a duplicated pointer to a bundle file that does not exist. The missing SKILL-MECHANICS.md is the most concrete defect, leaving the skill's own mechanics advice unreachable.

Suggestions

Ship the missing SKILL-MECHANICS.md (or remove both links to it) — the body defers frontmatter, invocation choice, and router-skill guidance to a file that is not in the bundle, so a reader following the pointer finds nothing.

Add one worked before/after example (a short document revised using the hierarchy, completion-criterion, and leading-word levers) to convert the conceptual definitions into concrete, executable guidance.

Tighten the essayistic passages — the 'elephant' negation mechanics and the 'price of human agency' aside restate what the model already knows, and the duplicated skill-mechanics pointer should appear once.

DimensionReasoningScore

Conciseness

Mostly dense and purposeful, but several passages are essayistic or re-explain what the model already knows — e.g. the "_Don't think of an elephant_, and the elephant is all there is" negation mechanics, and "it is the price of human agency; spend it where human judgement matters, remove it where it does not". Not a 4 because these padding passages and the duplicated SKILL-MECHANICS.md pointer (lines 8 and 59) could be tightened; not a 2 because nearly every line introduces a coined, load-bearing concept rather than generic filler.

3 / 5

Actionability

There are concrete tests and examples — "the test: the document should read like documentation written for the agent", "'fast, deterministic, low-overhead' → _tight_", "does it change behaviour versus the default?" — but most of the body defines abstract concepts (information hierarchy, two loads, leading words) rather than giving executable direction for writing or editing a document. Not a 4 because there is no worked procedure or before/after example showing the levers applied; better than a 2 because the embedded tests give specific, usable decision rules.

3 / 5

Workflow Clarity

The document is an all-reference skill (it says so itself: "all reference (a review's rules, this skill)"), so no ordered run of steps is expected, but it contains only fragments of sequence — "Defend in order: sharpen the bound first (local and cheap); only if it is irreducibly fuzzy..." — and no validation checkpoints for the editing work it guides. Not a 4 because applying the rules to an actual document has no prioritized checklist or review loop; above a 2 because the content is coherent and each section carries its own decision rule.

3 / 5

Progressive Disclosure

The body twice points to [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for "frontmatter, invocation choice, and router skills", but no such file exists — there are no references/, scripts/, or assets/ directories and no bundle file at all — so the skill's one disclosed reference is dangling and its mechanics content is simply missing. Scored against the actual (empty) bundle structure, the disclosure structure is broken despite the pointer itself being clearly signaled and conditional, which sits at the 2 anchor's level of structural failure rather than the 3 anchor's 'references present but not clearly signaled'.

2 / 5

Total

11

/

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 'Use when' clause naming concrete artifacts, giving it good trigger quality and completeness. The main weakness is that the capability statement itself is generic, listing no concrete writing actions.

DimensionReasoningScore

Specificity

The 'what' is minimal — "Writing documents for agents" — but the trigger clause names concrete artifacts and operations ("creating or editing skills, or modifying AGENTS.md or CLAUDE.md"), matching the anchor 'names domain and 1-2 concrete actions, but not comprehensive'. Not a 2 because the enumerated artifacts (skills, AGENTS.md, CLAUDE.md) go beyond a purely generic domain label; not a 4 because the capability statement itself lists no distinct writing actions.

3 / 5

Completeness

Both parts are present: what ("Writing documents for agents") and an explicit when ("Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md"). Not a 5 because the 'what' is a single generic phrase that does not enumerate concrete capabilities the way the 5-anchor does; clearly above a 3 since the 'when' is explicit rather than merely implied.

4 / 5

Trigger Term Quality

"creating or editing skills, or modifying AGENTS.md or CLAUDE.md" covers the natural phrases a user would say in this domain. Not a 5 because common variations like "documentation", "system prompt", or "writing a skill" are absent; not a 3 because the included terms are the exact file and artifact names users invoke.

4 / 5

Distinctiveness Conflict Risk

Triggers name specific artifacts (skills, AGENTS.md, CLAUDE.md) that are distinct from most other skills' triggers. Not a 5 because "Writing documents for agents" as a capability statement overlaps with general writing/editing/documentation skills; not a 3 because the named files carve out a recognizable niche.

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.rL4A1ZHm/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.