doc-coauthoring

This skill should be used when the user asks to co-author documentation, draft a proposal, write a technical spec, create a decision doc or RFC, or structure a substantial document through iterative collaboration and reader testing.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

85%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-architected, clearly sequenced three-stage workflow with strong actionability, validation checkpoints, and clean one-level-deep references. Its main weakness is verbosity from repeated announcement/inform directives and duplicated branch text.

Suggestions

Collapse the duplicated artifact vs. no-artifact branches (e.g., lines 141-157) into a single step with a short conditional note, removing the repeated 'Inform them that the initial structure...' phrasing.

Trim the 'Announce intention to...' / 'Inform them...' micro-directives — Claude will narrate progress naturally; keep only the directives that change user behavior.

Consider moving the manual no-sub-agent reader-testing steps (lines 297-333) into references/READER-TEST.md to shorten the body while keeping the sub-agent path inline.

Dimension	Reasoning	Score
Conciseness	It avoids explaining concepts Claude already knows, but is padded with repetitive announcement scaffolding ('Announce intention to...', 'Inform them that...') and near-duplicated artifact/no-artifact branches that could be tightened.	2 / 3
Actionability	Provides concrete, specific guidance throughout — named tool calls (`create_file`, `str_replace`), numbered step sequences, and copy-ready examples like 'Keep 1,4,7,9' / 'Remove 3 (duplicates 1)'.	3 / 3
Workflow Clarity	Three stages are clearly sequenced with explicit validation checkpoints (gap checks, 'after 3 consecutive iterations', reader-test pass/fail) and feedback loops that return problematic sections to refinement.	3 / 3
Progressive Disclosure	SKILL.md holds the core workflow while three real, one-level-deep references (RUNTIME-MATRIX, DOC-TYPES, READER-TEST) are clearly signaled inline and listed under a 'Reference Files' section with one-line descriptions.	3 / 3
	Total	11 / 12 Passed

Description

100%

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 strong description using third-person voice with an explicit 'should be used when' trigger, multiple concrete actions, and natural user-facing terms. It clearly answers both what the skill does and when to invoke it.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'co-author documentation, draft a proposal, write a technical spec, create a decision doc or RFC, or structure a substantial document' — matching the anchor for several specific concrete actions.	3 / 3
Completeness	Explicitly answers both what (co-author/draft/write/structure documents) and when via the clause 'This skill should be used when the user asks to...', satisfying the explicit-trigger requirement.	3 / 3
Trigger Term Quality	Covers natural terms users would actually say — 'draft a proposal', 'write a technical spec', 'decision doc', 'RFC', 'co-author documentation' — giving good coverage of common phrasings.	3 / 3
Distinctiveness Conflict Risk	The framing 'through iterative collaboration and reader testing' carves a clear niche distinct from generic writing help, with triggers unlikely to fire for unrelated skills.	3 / 3
	Total	12 / 12 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: Galaxy-Dawn/claude-scholar
Path: skills/doc-coauthoring/SKILL.md
Commit: 2f7766f

Reviewed: about 13 hours 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.