CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

65

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

73%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 well-sequenced workflow with unusually strong validation structure (exit conditions, iteration gates, reader-testing feedback loop) and genuinely actionable step-by-step guidance. Its weaknesses are verbosity — duplicated instructional lines and wordy 'announce intention to...' phrasing — and references that are catalogued at the end rather than signaled where they apply.

Suggestions

De-duplicate repeated instruction blocks: the 'Inform them that the initial structure... will be created' text appears in both the artifact and file branches of Stage 2, and the 'being specific helps learning' note appears twice in Step 5 — factor these into single statements, and compress 'Announce intention to X' scaffolding into direct imperatives.

Signal references at their point of use: point Stage 2's 'suggest 3-5 sections' step to `references/DOC-TYPES.md` and Stage 3's testing steps to `references/READER-TEST.md`, instead of surfacing both only in the tail 'Reference Files' listing.

Replace 'use the appropriate integration to fetch it' with a concrete decision path (e.g., 'use the available MCP connector/attachment read tool, or ask the user to paste the content'), since the runtime matrix already enumerates which environments have which capabilities.

DimensionReasoningScore

Conciseness

The body is mostly purposeful procedural instruction with no concept-explanation padding, but it is noticeably repetitive and could be tightened: 'Inform them that the initial structure with placeholders for all sections will be created' appears twice (lines 144 and 153), 'Note that being specific helps learning for the next sections' appears in both drafting paths (lines 202 and 207), and wordy scaffolding like 'Announce intention to predict what questions readers might ask' recurs throughout. This sits between the 2 anchor ('several unnecessary explanations or padded sections') and lean 4 — the duplication and verbose announce-style phrasing are exactly the 'could be tightened' material of the 3 anchor.

3 / 5

Actionability

The guidance is concrete and executable for an instruction-only skill: specific counts ('Generate 5-10 numbered questions', 'brainstorm [5-20] things'), example curation syntax ('Keep 1,4,7,9', 'Remove 3 (duplicates 1)', 'Combine 11 and 12'), and explicit tool directives ('Use `str_replace` to make edits (never reprint the whole doc)'). It is not a 5 because a few steps are underspecified — 'use the appropriate integration to fetch it' never names which integration or how, and `create_file`/`str_replace` assume a specific artifact harness whose availability the runtime matrix then has to hedge — leaving minor gaps.

4 / 5

Workflow Clarity

The three-stage workflow is clearly sequenced with explicit validation checkpoints and feedback loops: Stage 1 has an exit condition ('Sufficient context has been gathered when questions show understanding'), sections iterate until 'user is satisfied', a quality check triggers after '3 consecutive iterations with no substantial changes', a near-completion full-document review, and Stage 3's reader testing loops back to refinement for problematic sections with a final pass criterion ('When Reader Claude consistently answers questions correctly... the doc is ready'). This matches the top anchor's explicit validation steps and error-recovery loops; this is non-destructive authoring work, so no batch/destructive cap applies.

5 / 5

Progressive Disclosure

Three real, one-level-deep reference files exist (references/RUNTIME-MATRIX.md, DOC-TYPES.md, READER-TEST.md — all verified present) and are catalogued in a 'Reference Files' section with 'Load only what is needed'. RUNTIME-MATRIX.md is well-signaled from the body's runtime contract, but DOC-TYPES.md and READER-TEST.md are only surfaced in the tail listing rather than at their point of use (Stage 2's section-suggesting step and Stage 3's testing steps respectively), and the ~380-line body inlines detail that could partly live in those files. This is good structure with minor organization gaps — the 4 anchor — rather than the fully well-signaled navigation of a 5.

4 / 5

Total

16

/

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.

A strong description with an explicit 'should be used when' trigger clause, natural user phrasing, and a clear niche. Its main weakness is that the action list is one authoring capability projected across document types, with a few common synonyms (PRD, design doc, write-up) absent.

DimensionReasoningScore

Specificity

The description lists several concrete actions — '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' — but these are largely variations of one authoring action applied to document types, so coverage is broad without being comprehensive. It is not a 5 because it enumerates doc types rather than multiple distinct capabilities, and not a 3 because the collaboration/reader-testing mechanism adds concrete substance beyond a bare domain mention.

4 / 5

Completeness

It explicitly answers 'when' with concrete trigger phrasing ('This skill should be used when the user asks to...') and answers 'what' through the enumerated actions and the mechanism ('through iterative collaboration and reader testing'). Both what and when are explicit with concrete trigger phrases, matching the top anchor; a 4 would require the 'when' to be less explicit, which it is not.

5 / 5

Trigger Term Quality

Phrases like 'co-author documentation', 'draft a proposal', 'write a technical spec', 'decision doc', and 'RFC' are natural things users would say when needing this skill. A few common variations are missing ('write up', 'PRD', 'design doc', 'one-pager', 'memo'), which keeps it at the 'good coverage, a few natural terms missing' anchor rather than 5; it clearly exceeds the 3 anchor's 'missing common variations'.

4 / 5

Distinctiveness Conflict Risk

The co-authoring/reader-testing niche with RFC and decision-doc triggers is fairly distinct, but generic phrases like 'co-author documentation' and 'draft a proposal' could overlap with a general technical-writing or document-formatting skill. Minor overlap risk with closely related skills matches the 4 anchor; it lacks the clearly-unique trigger set of a 5.

4 / 5

Total

17

/

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

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

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.