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.

82

1.59x
Quality

61%

Does it follow best practices?

Impact

91%

1.59x

Average score across 7 eval scenarios

SecuritybySnyk

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/anthropic-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 of document types covered could create overlap with more specialized skills. The use of second person ('Guide users') slightly detracts from the preferred third-person voice.

Suggestions

Replace abstract phrases like 'transfer context' and 'refine content through iteration' with more concrete actions such as 'create outlines, draft sections, suggest structure, review for clarity'.

Consider narrowing the scope or adding more distinctive language about what makes this a 'structured workflow' (e.g., mention specific phases like 'outline → draft → review → finalize') to reduce potential overlap with general writing 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 formatting'.

2 / 3

Completeness

Clearly answers both 'what' (structured workflow for co-authoring documentation, transferring context, refining content, verifying readability) and 'when' (explicit 'Use when' and 'Trigger when' clauses with 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 this kind of help.

3 / 3

Distinctiveness Conflict Risk

While it specifies a structured workflow for documentation co-authoring, the broad scope covering 'documentation, proposals, technical specs, decision docs, or similar structured content' could overlap with general writing skills or individual document-type skills. The 'structured workflow' aspect provides some distinction but the category is still quite broad.

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 defines a well-structured three-stage co-authoring workflow with clear sequencing and validation checkpoints, which is its primary strength. However, it is severely over-verbose, explaining many things Claude already knows (how to parse freeform feedback, tone guidance, basic interaction patterns) and narrating what to say rather than specifying what to do. The monolithic presentation without any progressive disclosure makes it a heavy context burden despite the good underlying workflow design.

Suggestions

Cut the content by 50-60% by removing narration of what to say to users (e.g., 'Announce work will begin on...') and replacing with concise step descriptions. Claude knows how to communicate steps to users.

Split into separate files: SKILL.md as a concise overview (~50 lines), with STAGE-1-CONTEXT.md, STAGE-2-REFINEMENT.md, and STAGE-3-TESTING.md for detailed stage instructions.

Remove the 'Tips for Effective Guidance' section entirely - tone guidance ('be direct'), handling deviations ('give user agency'), and context management ('don't let gaps accumulate') are all things Claude already knows.

Add a concrete example of a completed section iteration (e.g., a sample brainstorm list, sample curation response, and resulting draft) to make the workflow more actionable rather than purely procedural.

DimensionReasoningScore

Conciseness

The skill is extremely verbose at ~300+ lines, with significant redundancy and over-explanation. It repeatedly explains things Claude already knows (how to handle user feedback, how to parse freeform responses, tone guidance like 'be direct'). Many sections could be condensed to a fraction of their length - e.g., the entire 'Tips for Effective Guidance' section states obvious behaviors, and the workflow narrates what to say to the user rather than just specifying the steps.

1 / 3

Actionability

The skill provides a clear structured workflow with specific steps, numbered questions to ask, and concrete interaction patterns. However, it lacks executable code/commands and relies heavily on descriptive prose rather than concrete examples. The brainstorming step says 'generate 5-20 numbered options' but doesn't show what good options look like. The guidance is procedural but often abstract ('use the appropriate integration').

2 / 3

Workflow Clarity

The three-stage workflow is clearly sequenced with explicit transition conditions between stages, exit conditions for each stage, and a feedback loop in the Reader Testing stage that loops back to refinement. The section-by-section refinement process has clear numbered steps (clarify → brainstorm → curate → gap check → draft → refine) with quality checking built in.

3 / 3

Progressive Disclosure

The entire workflow is presented as a monolithic wall of text in a single file with no references to external 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
boisenoise/skills-collections
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.