writing-for-agents

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

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/productivity/writing-for-agents/SKILL.md

Quality

Content

81%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 lean, well-organized instruction skill that assumes competence and provides actionable heuristics; it loses points only for some abstract guidance, the absence of executable examples, and a referenced file (SKILL-MECHANICS.md) that is not present in the bundle.

Suggestions

Add 1-2 short concrete before/after examples for the most abstract heuristics (e.g., a leading-word collapse: a multi-word restatement reduced to a single token) to lift actionability toward 5.

Either bundle the referenced SKILL-MECHANICS.md or soften the reference (e.g., note it is external/optional) so navigation is not broken.

For the reference-heavy sections, consider a one-line checklist of the pruning/no-op tests so the actionable heuristics are scannable at a glance.

Dimension	Reasoning	Score
Conciseness	Dense, information-rich prose that assumes Claude's intelligence and introduces specialized vocabulary (leading word, context pointer, information hierarchy, no-op, sediment) with no padding or re-explanation of basics; every line earns its tokens, matching anchor 5.	5 / 5
Actionability	Largely actionable via concrete heuristics and tests ('把 leading word 放到最前面', '逐句寻找 no-ops', the no-op test '是否相对于默认改变行为'), but no executable code/commands and some passages stay abstract ('寻找用 leading words 做重构的机会'); fits anchor 4 for mostly concrete guidance with minor gaps.	4 / 5
Workflow Clarity	A flat reference/rules skill (it names itself as an all-reference example) that is well-organized by section headings; no multi-step execution workflow with validation checkpoints is present or appropriate, so it sits at anchor 4 rather than 5 which requires explicit feedback loops.	4 / 5
Progressive Disclosure	Internally well-structured with clear ## sections and signaled one-level references to SKILL-MECHANICS.md, but no bundle files exist so the referenced sibling file is absent — a minor organization/navigation gap matching anchor 4.	4 / 5
	Total	17 / 20 Passed

Description

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

The description cleanly answers both what and when with a concrete trigger clause and a distinct niche, but the 'what' side is generic ('编写文档') rather than enumerating specific actions, capping specificity and completeness below 5.

Suggestions

Replace the generic action '编写文档' with 2-3 concrete actions (e.g., '起草、编辑和修剪 skills 与 AGENTS.md/CLAUDE.md 文档') to lift specificity.

Add natural synonyms users might say ('文档', 'documentation', 'instructions') alongside 'skills' for fuller trigger-term coverage.

Optionally add a file-extension or surface cue (e.g., 'SKILL.md', '.md') to further reduce conflict risk with unrelated doc skills.

Dimension	Reasoning	Score
Specificity	Names the domain ('为 agent 编写文档') and concrete trigger targets (skills, AGENTS.md, CLAUDE.md) but offers only a single generic action ('编写文档'); matches anchor 3 for domain plus 1-2 concrete actions without comprehensive coverage.	3 / 5
Completeness	Both 'what' ('为 agent 编写文档') and an explicit 'when' ('适用于...时' naming specific trigger conditions) are present; not 5 because the 'what' is thin and generic.	4 / 5
Trigger Term Quality	Concrete terms a user would name ('skills', 'AGENTS.md', 'CLAUDE.md') are present, but common natural variations and synonyms (docs, documentation, instructions) are missing, fitting anchor 3.	3 / 5
Distinctiveness Conflict Risk	Targets a clear niche (writing docs for agents, on skills/AGENTS.md/CLAUDE.md) with distinct triggers and low overlap risk; not 5 because the 'what' lacks the breadth seen in the anchor 5 example.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
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
Commit: 3f92a83

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.