CtrlK
BlogDocsLog inGet started
Tessl Logo

writing-for-agents

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

60

Quality

76%

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/skills/writing-for-agents/SKILL.md

The canonical home for this skill is writing-for-agents in mattpocock/skills

SKILL.md
Quality
Evals
Security

Quality

Content

65%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 tight, well-organized reference document with genuinely actionable heuristics and no wasted tokens. Its two real defects are the absence of any ordered application workflow (it teaches the levers but never sequences their use) and a twice-referenced SKILL-MECHANICS.md that is missing from the bundle, leaving both context pointers dangling.

Suggestions

Add or restore SKILL-MECHANICS.md: the body points to it twice ('read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills'; 'By invocation, skill-specific: see SKILL-MECHANICS.md'), but no such file exists in the bundle — every pointer to it is currently a dead link.

Add a short ordered procedure or checklist for applying the framework when editing a document (e.g. prune no-ops → collapse restatements into leading words → verify each pointer's wording → check the hierarchy per branch), so the reference material has an executable application sequence.

Trim the essayistic connective prose (e.g. 'You win twice: fewer tokens, and a sharper hook...', 'Assume every document is carrying restatements that leading words retire. Go find them.') to push conciseness from efficient to lean.

DimensionReasoningScore

Conciseness

The body is dense and assumes competence — every section introduces a distinct lever (context pointers, the two loads, the hierarchy, leading words) with no padding and no explanation of concepts the model already knows. Minor essayistic passages ("You win twice... Go find them", the coining examples, the elephant aside) could be trimmed, which fits anchor 4's "minor instances of over-explanation" rather than anchor 3's unnecessary explanation.

4 / 5

Actionability

Concrete, applicable guidance throughout: "Front-load the leading word", "defend in order: sharpen the bound first", "delete the whole sentence rather than trim words from it", the no-op test ("does it change behaviour versus the default?"), and worked coining examples ("fast, deterministic, low-overhead" → tight). Per the rubric's instruction-skill note, absent code is not penalized, but several sections are conceptual framework the agent must translate, keeping it below anchor 5's copy-paste-ready bar.

4 / 5

Workflow Clarity

This is an all-reference skill ("all reference (a review's rules, this skill)") with clear section organization but no sequence at all — no ordered procedure, checklist, or worked application of the framework to an actual document. It cannot reach anchor 4's "clear sequence with most checkpoints" because there is no sequence; it is above anchor 2 only because the conceptual structure is coherent and well-sectioned.

3 / 5

Progressive Disclosure

The in-file structure is good (clear ## headings, one concept per section) and the reference is clearly signaled — "read SKILL-MECHANICS.md for frontmatter, invocation choice, and router skills" — but SKILL-MECHANICS.md does not exist anywhere in the bundle, so both pointers dangle and navigation fails at exactly the point disclosure is meant to serve. Not anchor 4 ("references mostly clear; minor organization gaps") because a missing referenced file is a navigation failure, not a minor gap; not anchor 2 because the reference is neither buried nor is the content that belongs separate merely inlined.

3 / 5

Total

14

/

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 concise, well-formed description that answers both what and when with explicit trigger guidance and the exact artifacts users would name. Its only weaknesses are a generic action verb in the what-clause and some missing natural synonyms (e.g. "documentation", "skill description").

DimensionReasoningScore

Specificity

"Writing documents for agents" names the domain with a single generic action verb, matching the anchor-2 shape of "Processes PDF files"; the concrete artifacts ("creating or editing skills, or modifying AGENTS.md or CLAUDE.md") lift it to anchor 3, which expects the domain plus 1-2 concrete actions. It is not anchor 4 because only one action (writing) is described rather than several specific ones.

3 / 5

Completeness

It explicitly answers both questions: the what ("Writing documents for agents") and an explicit "Use when..." clause with concrete trigger phrases ("creating or editing skills, or modifying AGENTS.md or CLAUDE.md"). This matches the anchor-5 example's structure exactly; anchor 4 requires a 'when' that could be more explicit, which is not the case here.

5 / 5

Trigger Term Quality

Natural phrases a user would actually say are present — "creating or editing skills", "AGENTS.md", "CLAUDE.md" — giving good keyword coverage. It falls short of anchor 5's comprehensive synonym/extension coverage because common variations like "documentation", "skill description", ".claude", or "memory files" are absent.

4 / 5

Distinctiveness Conflict Risk

The niche (writing agent-consumed documents: skills, AGENTS.md, CLAUDE.md) is mostly distinct with clear triggers, but "writing documents" leaves minor overlap risk with general documentation or writing skills. It is not anchor 5 because the what-clause is broad enough to collide with adjacent docs/editing skills.

4 / 5

Total

16

/

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
koenighotze/wheel-of-meeting
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.