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/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 documentation types could create overlap with other writing-related skills.

Suggestions

Replace abstract phrases like 'transfer context' and 'refine content through iteration' with more concrete actions such as 'create outlines, draft sections, restructure content, add examples'.

Consider narrowing the scope or adding more distinctive workflow-specific language to reduce potential overlap with general writing or template 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 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 with a structured workflow, the broad scope covering 'proposals, technical specs, decision docs, or similar structured content' could overlap with more specific writing or template skills. The 'structured workflow' aspect provides some distinction but the category is still fairly 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 provides a well-structured three-stage workflow for document co-authoring with clear sequencing and validation steps, but suffers significantly from verbosity and poor progressive disclosure. The content is roughly 3-4x longer than necessary, repeating conditional logic (artifacts vs files, integrations vs no integrations) inline rather than abstracting it, and explaining concepts Claude already understands. The lack of concrete examples (sample questions, sample brainstorming output, sample document sections) makes it less actionable despite its detailed procedural structure.

Suggestions

Reduce content by 50-60% by eliminating redundant conditional branches (consolidate artifact vs file handling into a single pattern), removing explanations of obvious concepts, and trusting Claude to handle edge cases without explicit instruction for each one.

Split into multiple files: main SKILL.md as overview (~50 lines) with links to STAGE1-CONTEXT.md, STAGE2-REFINEMENT.md, and STAGE3-TESTING.md for detailed stage instructions.

Add concrete examples: include a sample set of clarifying questions for a specific doc type, a sample brainstorming list with curation response, and a sample Reader Testing exchange to make the workflow tangible.

Remove the 'Tips for Effective Guidance' section entirely - tone guidance, context management advice, and 'quality over speed' are things Claude already knows and don't add actionable value.

DimensionReasoningScore

Conciseness

The skill is extremely verbose at ~300+ lines, with significant redundancy and explanations of things Claude already knows (e.g., explaining what brainstorming is, how to parse freeform feedback, what 'shorthand' means). Many sections repeat instructions in slightly different ways (e.g., artifact vs file handling is repeated multiple times). The tone guidance at the end ('Be direct and procedural') is ironic given the skill itself is not concise.

1 / 3

Actionability

The skill provides a clear structured workflow with specific steps, but lacks concrete executable examples. There are no actual code snippets, no example document outputs, no sample clarifying questions, and no template for what a brainstorming list looks like. Instructions like 'Generate 5-10 numbered questions' and 'Brainstorm 5-20 things' are directional but not concrete enough to be copy-paste actionable.

2 / 3

Workflow Clarity

The three-stage workflow is clearly sequenced with explicit transition conditions between stages, validation checkpoints (Reader Testing as verification), feedback loops (iterative refinement until satisfied, loop back from testing to refinement), and clear exit conditions for each stage. The sub-steps within each stage are well-ordered.

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.