CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

writing-for-agents

为 agent 编写文档。适用于创建或编辑 skills,或修改 AGENTS.md 或 CLAUDE.md 时。

Quality

73%

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 ./skills/productivity/writing-for-agents/SKILL.md
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 dense, high-signal reference skill that assumes the reader's intelligence, defines a coherent leading-word vocabulary, and gives concrete heuristics with worked examples. Its weaknesses are the absence of any end-to-end procedure tying the principles into an executable workflow, and two pointers to SKILL-MECHANICS.md that dangle because the file is not present in the bundle.

Suggestions

Ship SKILL-MECHANICS.md alongside SKILL.md — both pointers to it in the body dangle, making the disclosed material unreachable.

Add an ordered review procedure (e.g., pointers → loads → information hierarchy → completion criteria → pruning) so the flat reference material has an explicit execution sequence.

Consolidate the scattered 检验标准/test criteria into an explicit end-of-document checklist so the implicit checkpoints become usable validation steps.

DimensionReasoningScore

Conciseness

The body is exceptionally dense original methodology with essentially no explanation of concepts Claude already knows — it defines its own compact vocabulary (context pointer, branch, sediment, no-op) and pushes mechanics detail out to a pointer. Minor over-explanation remains: the negation section spells out the well-known 'don't think of an elephant' effect at length, and a few parentheticals restate a point already made (e.g., the duplication-vs-scattered contrast inside the co-location section), which keeps it below anchor 5.

4 / 5

Actionability

Guidance is concrete and executable for a writing skill: worked refactor examples ("fast, deterministic, low-overhead" → _tight_; "a loop you believe in" → _red_), explicit test criteria ("它是否相对于默认改变行为?"), and ordered procedures ("先 sharpen 边界…只有当…才通过拆分 sequence 隐藏后续 steps"). Not 5 because it is principles-first — there is no end-to-end procedure for applying these checks to an actual document, leaving the agent to assemble the process itself.

4 / 5

Workflow Clarity

Sequences exist only locally (the premature-completion defense order, the polish-wording-before-inlining order) and the 检验标准 items act as implicit checkpoints, but there is no overall execution sequence for writing or reviewing a document — the sections are ordered by concept, not by process, and checkpoints are scattered rather than explicit. Not 4 because a clear top-level sequence with most checkpoints present is absent; not 2 because the local orderings and test criteria are coherent and well-defined.

3 / 5

Progressive Disclosure

Sections are well-organized and skill mechanics are appropriately disclosed behind a clearly signaled one-level pointer ("阅读 [SKILL-MECHANICS.md] 了解 frontmatter、invocation 选择以及 router skills"). However, both references in the body point to SKILL-MECHANICS.md, which is absent from the bundle (no references/, scripts/, or assets/ directories and no sibling file) — the disclosed material is unreachable as shipped, so the navigation the structure promises is broken. Not 4 because 'references mostly clear' presumes the referenced files actually resolve.

3 / 5

Total

14

/

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 well-targeted 'when' clause naming the exact artifacts (skills, AGENTS.md, CLAUDE.md). Its main weakness is a thin 'what': a single generic action verb with no enumeration of the concrete capabilities the skill delivers.

Suggestions

Enumerate the concrete capabilities in the 'what' half (e.g., structure content into information hierarchies, craft context pointers and trigger descriptions, prune token overhead) so it goes beyond 'write documentation'.

Add natural synonyms users would say when reaching for this skill — 'documentation', 'agent instructions', 'guidelines', 'memory files' — alongside skills / AGENTS.md / CLAUDE.md to broaden trigger coverage.

DimensionReasoningScore

Specificity

The 'what' is a single generic action ("为 agent 编写文档" — write documentation for agents) with no enumeration of the skill's actual capabilities (structuring hierarchies, crafting pointers, pruning). The trigger clause does list concrete operations ("创建或编辑 skills,或修改 AGENTS.md 或 CLAUDE.md"), which puts it at 'domain plus 1-2 concrete actions, not comprehensive' — not 4 because it never lists the several specific actions the skill performs; not 2 because the named artifacts and edit/modify operations go beyond a bare domain label like 'Processes PDF files'.

3 / 5

Completeness

Both parts are explicitly present: a clear 'what' ("为 agent 编写文档") and an explicit 'when' clause with concrete triggers ("适用于创建或编辑 skills,或修改 AGENTS.md 或 CLAUDE.md 时"). Not 5 because the 'what' is one minimal generic verb with no capability enumeration, unlike the anchor-5 example's multi-action statement; not 3 because the 'when' is explicit and specific rather than missing or weakly implied.

4 / 5

Trigger Term Quality

Triggers use the exact artifact names a user would naturally say — "skills", "AGENTS.md", "CLAUDE.md" — paired with the verbs 创建/编辑/修改 (create/edit/modify). Good coverage, but a few natural terms are missing (e.g., "documentation", "agent instructions", "memory files", "guidelines"), so it falls just short of anchor 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

It carves a clear niche (documentation written for agent consumption) with distinct, artifact-named triggers unlikely to fire for unrelated skills. Minor overlap risk remains with closely related skills such as CLAUDE.md initialization or general skill-authoring workflows, which keeps it from anchor 5.

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

vinvcn/mattpocock-skills-zh-CN

Path

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