CtrlK
BlogDocsLog inGet started
Tessl Logo

doc-coauthoring

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

1.60x
Quality

61%

Does it follow best practices?

Impact

90%

1.60x

Average score across 7 eval scenarios

SecuritybySnyk

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/doc-coauthoring/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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.

DimensionReasoningScore

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.

DimensionReasoningScore

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
anthropics/skills
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.