Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
81
61%
Does it follow best practices?
Impact
90%
1.60xAverage score across 7 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/doc-coauthoring/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description that excels in completeness with explicit 'Use when' and 'Trigger when' clauses, and provides good trigger term coverage. Its main weaknesses are that the specific capabilities described are somewhat abstract (e.g., 'transfer context', 'refine content') rather than concrete actions, and the broad scope could create overlap with more specialized documentation skills.
Suggestions
Replace abstract phrases like 'transfer context' and 'refine content through iteration' with more concrete actions such as 'create outlines, draft sections, incorporate feedback, restructure content'.
Consider narrowing the scope or adding more distinctive language about what makes this a 'structured workflow' (e.g., mention specific phases or steps) to reduce potential overlap with other writing-related skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (documentation co-authoring) and mentions some actions like 'transfer context', 'refine content through iteration', and 'verify the doc works for readers', but these are somewhat abstract rather than concrete, specific actions like 'create outlines, draft sections, add diagrams'. | 2 / 3 |
Completeness | Clearly answers both 'what' (structured workflow for co-authoring documentation with context transfer, iterative refinement, and reader verification) and 'when' (explicit 'Use when' and 'Trigger when' clauses listing specific scenarios like writing docs, creating proposals, drafting specs). | 3 / 3 |
Trigger Term Quality | Good coverage of natural terms users would say: 'write documentation', 'proposals', 'technical specs', 'decision docs', 'writing docs', 'creating proposals', 'drafting specs', 'documentation tasks'. These are terms users would naturally use when requesting help with documentation. | 3 / 3 |
Distinctiveness Conflict Risk | While it specifies documentation co-authoring, the broad scope covering 'proposals, technical specs, decision docs, or similar structured content' could overlap with more specific skills for proposals or technical specs. The 'structured workflow' aspect adds some distinctiveness but the scope is still quite wide. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a well-structured three-stage workflow for document co-authoring with clear sequencing and good feedback loops, which is its primary strength. However, it is excessively verbose—much of the content describes what Claude should say or announce rather than providing lean directives, and it explains concepts Claude already understands. The monolithic structure with no supporting files makes it a poor fit for the progressive disclosure principle given its substantial length.
Suggestions
Reduce verbosity by 50%+: replace meta-instructions like 'Announce intention to re-read the entire document' with direct imperatives like 'Re-read full document. Check for: flow, redundancy, contradictions, filler.' Claude doesn't need to be told to announce things.
Split into multiple files: create separate files for each stage (e.g., STAGE1_CONTEXT.md, STAGE2_REFINEMENT.md, STAGE3_TESTING.md) and keep SKILL.md as a concise overview with navigation links.
Add concrete tool invocation examples: instead of 'use the appropriate integration to fetch it', show specific MCP tool calls or artifact creation syntax that Claude can directly execute.
Remove redundant conditional branching prose: the artifact vs file and sub-agent vs manual paths repeat similar instructions with slight variations—consolidate into a single flow with brief conditional notes.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~300+ lines, with extensive procedural narration that Claude could infer. Phrases like 'Inform them they can answer in shorthand' and 'Announce work will begin on the [SECTION NAME] section' are meta-instructions about what to say rather than lean directives. Much of the content reads like a tutorial explaining the workflow to a human rather than efficient instructions for Claude. | 1 / 3 |
Actionability | The skill provides a clear structured process with specific steps, numbered question counts (5-10, 5-20), and concrete examples of user shorthand ('1: yes, 2: see #channel'). However, it lacks executable code examples, specific tool invocation syntax, and concrete output templates. Guidance like 'use the appropriate integration' is vague rather than specifying exact tool calls. | 2 / 3 |
Workflow Clarity | The three-stage workflow is clearly sequenced with explicit entry/exit conditions for each stage, well-defined sub-steps within each stage, quality checkpoints (e.g., 'after 3 consecutive iterations with no substantial changes'), and feedback loops (reader testing → loop back to refinement). The branching logic for different environments (artifacts vs files, sub-agents vs manual) is clearly handled. | 3 / 3 |
Progressive Disclosure | The entire workflow is a monolithic wall of text in a single file with no references to supporting files. Given the length and complexity (~300+ lines covering three major stages with multiple sub-steps each), this content would benefit significantly from being split into separate files for each stage, with the main SKILL.md serving as an overview with navigation links. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
da20c92
Table of Contents
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.