doc-coauthoring

This skill provides a structured workflow for guiding users through collaborative document creation. Act as an active guide, walking users through three stages: Context Gathering, Refinement & Structure, and Reader Testing.

Quality

36%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/doc-coauthoring/SKILL.md

Quality

Content

44%Scale 1-5

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 collaborative writing workflow with clear sequencing and transitions, but suffers from significant verbosity and lack of concrete examples. The procedural steps are clear in intent but abstract in execution—there are no sample outputs, example questions, or template snippets that would make the guidance truly actionable. The entire workflow is crammed into one long file with no progressive disclosure.

Suggestions

Cut content by 40-50%: remove explanations of rationale Claude can infer, consolidate repeated instructions about shorthand/info-dumping, and eliminate redundant phrasing across the artifact vs file branches.

Add concrete examples: include 2-3 sample clarifying questions, a sample brainstorm list with numbered options, and an example str_replace edit to make the workflow actionable rather than abstract.

Split into multiple files: extract Stage 2 (Refinement) and Stage 3 (Reader Testing) into separate referenced files, keeping SKILL.md as a concise overview with navigation links.

Add a brief example interaction snippet showing what a typical Stage 1 exchange looks like, so Claude has a concrete model to follow rather than just procedural descriptions.

Dimension	Reasoning	Score
Conciseness	The skill is significantly verbose at ~300+ lines. It over-explains process steps that Claude could infer (e.g., explaining what shorthand means, repeatedly telling the user they can 'info dump'), restates the description in the body, and includes substantial padding like 'Don't try to sell the approach - just execute it' and explanations of what Reader Testing is. Many sections could be condensed to bullet points.	2 / 5
Actionability	The skill provides a clear procedural framework with specific steps, but lacks concrete examples of actual output. There are no example documents, no sample clarifying questions, no example brainstorm lists, and no example of what a 'surgical edit' via str_replace looks like. The guidance is structured but remains at the level of meta-instructions rather than executable specifics.	3 / 5
Workflow Clarity	The three-stage workflow is well-sequenced with clear transitions and exit conditions between stages. The Reader Testing stage includes a validation/feedback loop. However, some steps within Stage 2 (like the quality checking trigger of '3 consecutive iterations') are somewhat vague, and the branching logic between artifacts vs files vs sub-agents vs manual testing adds complexity without always being crisp about which path to take.	4 / 5
Progressive Disclosure	Everything is inlined into a single monolithic SKILL.md with no bundle files. The content is long enough that sections like the detailed Reader Testing approaches (sub-agent vs manual), the Tips section, and the Stage 2 refinement loop could benefit from being split into separate reference files. There are no external references despite the document's substantial length.	2 / 5
	Total	11 / 20 Passed

Description

28%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.

The description is too vague and process-oriented rather than action-oriented. It describes a workflow structure but fails to specify what concrete outputs or actions it performs, lacks natural trigger terms users would say, and has no explicit 'when to use' guidance. The use of second person ('guiding users', 'walking users through') and imperative voice ('Act as an active guide') also deviates from the preferred third-person style.

Suggestions

Add a 'Use when...' clause with natural trigger terms like 'write a document', 'draft', 'collaborative writing', 'document outline', or 'review my writing'.

Replace vague process descriptions with concrete actions, e.g., 'Gathers requirements, creates structured outlines, generates drafts, and tests readability with target audience criteria'.

Rewrite in third person voice ('Guides collaborative document creation through three stages...') instead of imperative ('Act as an active guide').

Dimension	Reasoning	Score
Specificity	Names the domain (document creation) and mentions three stages by name, but the actions described are vague ('guiding users', 'walking users through'). The stage names hint at structure but don't describe concrete actions like 'outlines sections', 'generates drafts', or 'tests readability'.	2 / 5
Completeness	Has a weak 'what' (structured workflow for collaborative document creation) but no explicit 'when' clause. There is no 'Use when...' guidance or trigger phrases to help Claude know when to select this skill.	2 / 5
Trigger Term Quality	Contains 'document creation' and 'collaborative' as keywords, but misses natural user phrases like 'write a document', 'draft', 'outline', 'review', 'feedback', or specific document types. Users are unlikely to say 'context gathering' or 'reader testing'.	2 / 5
Distinctiveness Conflict Risk	The three-stage workflow (Context Gathering, Refinement & Structure, Reader Testing) provides some distinctiveness, but 'document creation' is broad enough to overlap with many writing, editing, or drafting skills.	3 / 5
	Total	9 / 20 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/doc-coauthoring/SKILL.md
Commit: 57c135b

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.