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

84%

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

The content is a well-structured, highly actionable workflow with clear sequencing, validation checkpoints, and clean progressive disclosure to real reference files. Its main weakness is repetition of the artifact-vs-file and tool-call guidance across multiple sections, which inflates length without adding value.

Suggestions

Consolidate the artifact-vs-file branching into a single decision point and reference it from Stage 2 and the Tips section instead of restating 'Use create_file / Use str_replace' in three places.

Deduplicate the shorthand-answer guidance ('Inform them they can answer in shorthand or dump information') which appears with minor variation in Stage 1, the clarifying-questions block, and Step 1 of Stage 2.

Tighten or move the integration/connector explanation (currently repeated in Stage 1 'Info Dumping' and 'During context gathering') into references/RUNTIME-MATRIX.md to reduce token load in the main body.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and procedural, but restates the artifact-vs-file branching in multiple places (Stage 2 drafting, refinement, and the Tips section repeat 'Use create_file / Use str_replace') and rephrases shorthand-answer guidance several times, which is unnecessary padding.	3 / 5
Actionability	Provides fully executable, specific guidance throughout — exact question counts, brainstorm ranges ('5-20 options'), concrete curation examples ('Keep 1,4,7,9; Remove 3; Combine 11 and 12'), and named tool calls (create_file, str_replace) — covering common cases.	5 / 5
Workflow Clarity	A clear three-stage sequence with explicit steps, named exit conditions, and feedback loops (quality-check after 3 iterations, reader-test loop back to refinement) matches the top anchor for sequenced validation and error recovery.	5 / 5
Progressive Disclosure	The body is an overview pointing to three real, one-level-deep reference files (RUNTIME-MATRIX.md, DOC-TYPES.md, READER-TEST.md) in a clearly signaled 'Reference Files' section with a 'Load only what is needed' cue, with content appropriately split.	5 / 5
	Total	18 / 20 Passed

Description

83%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 clearly states both the capability and the trigger conditions with natural, user-likely phrases, distinguishing it well from generic doc skills. Minor improvements in synonym coverage and absolute distinctiveness would push it to the top band.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('co-author documentation, draft a proposal, write a technical spec, create a decision doc or RFC, structure a substantial document') with only minor gaps in coverage, fitting the 'several specific actions' anchor rather than the fully comprehensive 5.	4 / 5
Completeness	Explicitly answers both what (co-author/draft/write/structure documents) and when ('should be used when the user asks to...') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Good keyword coverage with natural phrases users actually say ('draft a proposal', 'write a technical spec', 'decision doc', 'RFC'), but a few synonyms or common variations are missing, so it sits between anchor 3 and 5.	4 / 5
Distinctiveness Conflict Risk	Has a clear niche (iterative co-authoring with reader testing) and distinct triggers, with only minor overlap risk against generic documentation skills, fitting 'mostly distinct' rather than the minimal-conflict 5.	4 / 5
	Total	17 / 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
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: 6ed46da

Reviewed: 12 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.