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

68%

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.wfQxtN2o/SKILL.md

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

SKILL.md
Quality
Evals
Security

Quality

Content

57%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 densely written, concept-rich reference that models its own principles (tight leading words, no padding, no restatement of known material). Its weaknesses are the missing referenced bundle file SKILL-MECHANICS.md, the absence of a concrete applied example or end-to-end procedure, and a few rhetorical passages that could be tightened.

Suggestions

Include SKILL-MECHANICS.md in the bundle or inline its guidance — both links in the body point to a file that does not exist alongside SKILL.md.

Add one worked before/after example showing the levers applied to a short real document or pointer, to convert the abstract principles into executable guidance.

Provide an explicit ordered procedure (e.g., a review order: pointers → loads → hierarchy → completion criteria → leading words → pruning) so the reference can be applied as a workflow.

DimensionReasoningScore

Conciseness

The body is dense and non-padded, teaching genuinely novel concepts (context pointers, the two loads, leading words) with tight tests like "does it change behaviour versus the default?" rather than restating what Claude already knows. Not a 5 because several rhetorical passages — the don't-think-of-an-elephant elaboration and "it is the price of human agency" — could be trimmed without losing guidance.

4 / 5

Actionability

Concrete guidance exists — the branch disclosure test, the transformation "fast, deterministic, low-overhead" → _tight_, and the ordered defense "sharpen the bound first; only if... hide the later steps" — but much of the body is abstract principle with no worked before/after example applying the levers to a real document. It is not a 4 because the concrete techniques are a minority of the text and a reader is left to construct the application themselves; not a 2 because the concrete tests and examples are genuinely usable.

3 / 5

Workflow Clarity

This is an all-reference skill (as it states itself), and its concept sections are coherent with embedded mini-orderings, but no explicit end-to-end process is given for applying the levers to a document, and no validation checkpoints exist for judging whether a revision worked. It is not a 4 because there is no sequence a reader can follow start to finish, and not a 2 because the internal structure is coherent rather than gapped.

3 / 5

Progressive Disclosure

Sections are clearly organized and the one reference is well-signaled with a firing condition ("When the document you're writing is a skill, read SKILL-MECHANICS.md"), but both links point to SKILL-MECHANICS.md, which does not exist in the bundle — a dangling pointer — and no other disclosed material exists. It is not a 2 because the in-file structure is strong and the reference is clearly signaled rather than buried; not a 4 because the single referenced file is missing.

3 / 5

Total

13

/

20

Passed

Description

65%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 well-formed description with an explicit, natural trigger clause naming concrete targets. Its main weakness is the vague, single-verb capability statement that leaves the skill's concrete levers undisclosed.

Suggestions

Enumerate one or two concrete actions in the what-statement, e.g. "Sharpen context-pointer wording, apply progressive disclosure, and prune no-op lines when writing documents for agents."

Add natural trigger variations the body already covers, such as writing or editing documentation, reference docs, or agent prompts.

DimensionReasoningScore

Specificity

The description names the domain ("Writing documents for agents") but offers only one broad generic action, matching the anchor-2 example "Processes PDF files". It is not a 3 because no concrete actions are enumerated — nothing like sharpening pointer wording or applying progressive disclosure.

2 / 5

Completeness

Both parts are present: a "what" ("Writing documents for agents") and an explicit "Use when..." clause with concrete triggers. Not a 5 because the "what" is broad and vague compared to the anchor-5 pattern of enumerated concrete actions.

4 / 5

Trigger Term Quality

Triggers "creating or editing skills" and "modifying AGENTS.md or CLAUDE.md" are natural phrases users would say, including exact file names. Not a 5 because common variations the body itself covers (documentation, docs, prompts) are missing.

4 / 5

Distinctiveness Conflict Risk

The triggers name distinctive artifacts (skills, AGENTS.md, CLAUDE.md), giving a clear niche with minimal conflict risk. Not a 5 because "Writing documents for agents" as the capability statement overlaps broadly with generic documentation or writing skills.

4 / 5

Total

14

/

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