write-docs — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited write-docs (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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 and Structure, and Reader Testing.
Trigger conditions:
Initial offer: Offer the user a structured workflow for collaborating on the document. Explain the three stages:
Explain that this approach helps ensure the document works well when others read it (including when they paste it into Claude). Ask whether they want to try this workflow or prefer to work freeform.
If the user declines, work freeform. If they agree, proceed to Stage 1.
Goal: Close the gap between what the user knows and what Claude knows, so smart prompts can be given afterward.
Begin by asking the user to provide meta-context about the document:
Tell them they can answer in shorthand or dump information however is convenient.
If the user provides a template or mentions a document type:
If the user mentions editing an existing shared document:
Once initial questions are answered, encourage the user to dump all the context they have. Request information such as:
Advise them not to worry about organization — just get it all out. Offer several ways to provide context:
If integrations are available (e.g., Slack, Teams, Google Drive, SharePoint, or other MCP servers), mention they can be used to pull context directly.
If no integrations are detected and Claude.ai or the Claude app is in use: Offer to enable connectors in Claude settings to allow pulling context from chat tools and document stores directly.
Tell them clarifying questions will follow once they finish their initial dump.
During context gathering:
Asking clarifying questions:
When the user signals they have finished the initial dump (or after substantial context has been provided), ask clarifying questions to confirm understanding:
Generate 5-10 numbered questions based on context gaps.
Tell them they can answer in shorthand (e.g., "1: yes, 2: see #channel, 3: no because backwards compat"), link to more documents, point to channels to read, or just keep dumping. Whatever is most efficient.
Exit condition: Sufficient context has been gathered when the questions reveal understanding — when edge cases and trade-offs can be discussed without needing to explain the basics.
Transition: Ask whether there is more context to provide at this stage, or whether it is time to move on to drafting the document.
If the user wants to add more, allow it. When ready, move to Stage 2.
Goal: Build the document section by section through brainstorming, selection, and iterative refinement.
Instructions to the user: Explain that the document will be built section by section. For each section:
Begin with the section that has the most unknowns (usually the main decision/proposal), then work through the rest.
Section order:
If the document structure is clear: Ask which section they would like to start with.
Suggest starting with the section with the most unknowns. For decision documents this is usually the main proposal. For specs this is usually the technical approach. Summary sections are best left for the end.
If the user does not know which sections they need: Based on document type and template, suggest 3-5 sections appropriate for the document type.
Ask whether this structure works, or whether they want to adjust it.
Once the structure is agreed upon:
Create an initial document structure with placeholder text for all sections.
If artifact access is available: Use create_file to create an artifact. This gives both Claude and the user a skeleton to work from.
Tell them an initial structure will be created with placeholders for all sections.
Create the artifact with all section headings and brief placeholder text such as "[To be written]" or "[Content here]".
Provide a link to the skeleton and indicate it is time to fill in each section.
If artifact access is not available: Create a markdown file in the working directory. Name it appropriately (e.g., decision-doc.md, technical-spec.md).
Tell them an initial structure will be created with placeholders for all sections.
Create the file with all section headings and placeholder text.
Confirm a file with that name was created and indicate it is time to fill in each section.
For each section:
Announce that work is starting on section [SECTION NAME]. Ask 5-10 clarifying questions about what to include:
Generate 5-10 specific questions based on the context and the section's purpose.
Tell them they can answer in shorthand or just point to what is important to cover.
For section [SECTION NAME], brainstorm 5-20 things that could be included, depending on section complexity. Look for:
Generate 5-20 numbered options based on the complexity of the section. At the end, offer to brainstorm more if they want additional options.
Ask which items to keep, remove, or combine. Request short rationale to help learn priorities for subsequent sections.
Provide examples:
If the user gives freeform feedback (e.g., "looks good" or "I like most of it, but...") instead of numbered choices, extract their preferences and continue. Parse what they want to keep/remove/change and apply it.
Based on what they selected, ask whether there is anything important missing for section [SECTION NAME].
Use str_replace to replace the placeholder text for this section with the actual drafted content.
Announce that section [SECTION NAME] will now be drafted based on what they selected.
If using artifacts: After drafting, provide a link to the artifact.
Ask them to read it and indicate what to change. Note that specificity helps in learning for subsequent sections.
If using a file (no artifacts): After drafting, confirm completion.
Tell them section [SECTION NAME] is drafted in [filename]. Ask them to read it and indicate what to change. Note that specificity helps in learning for subsequent sections.
Key instruction to the user (include while drafting the first section): Note: Instead of editing the document directly, ask them to indicate what to change. This helps learn their style for future sections. For example: "Remove the X bullet - already covered by Y" or "Make the third paragraph more concise".
As the user gives feedback:
str_replace to make edits (never retype the whole document)Continue iterating until the user is satisfied with the section.
After 3 consecutive iterations without substantive changes, ask whether anything can be removed without losing important information.
When the section is ready, confirm that [SECTION NAME] is complete. Ask whether they are ready to move on to the next section.
Repeat for all sections.
As you approach completion (80%+ of sections done), announce the intent to re-read the entire document and check:
Read the full document and provide feedback.
When all sections are drafted and refined: Announce that all sections are drafted. Indicate the intent to walk through the full document once more.
Review for overall coherence, flow, and completeness.
Provide any final suggestions.
Ask whether they are ready to move to Reader Testing, or whether they want to refine more.
Goal: Test the document with a fresh Claude (without leaking context) to verify it works for readers.
Instructions to the user: Explain that testing will now happen to see whether the document actually works for readers. This catches blind spots — things that make sense to the authors but may confuse others.
If sub-agent access is available (e.g., in Claude Code):
Carry out testing directly, without user involvement.
Announce the intent to predict what questions readers might ask while trying to evaluate this document.
Generate 5-10 questions readers would realistically ask.
Announce that these questions will be tested with a fresh Claude instance (no context from this conversation).
For each question, invoke a sub-agent, passing only the document content and the question.
Summarize what Reader Claude got right/wrong on each question.
Announce that additional checks will be run.
Invoke a sub-agent to check for ambiguity, false assumptions, contradictions.
Summarize the issues found.
If issues are found: Report that Reader Claude struggled with specific issues.
List the specific problems.
Indicate the intent to fix these gaps.
Return to refining the problematic sections.
If no sub-agent access is available (e.g., the claude.ai web interface):
The user will need to run the test manually.
Ask what questions people might ask while trying to evaluate this document. What would they type into Claude.ai?
Generate 5-10 questions readers would realistically ask.
Provide testing instructions:
For each question, instruct Reader Claude to provide:
Check whether Reader Claude gives correct answers or misinterprets anything.
Also ask Reader Claude:
Ask what Reader Claude got wrong or struggled with. Indicate the intent to fix these gaps.
Return to refining any problematic sections.
When Reader Claude consistently answers questions correctly and surfaces no new gaps or ambiguities, the document is ready.
When Reader Testing is complete: Announce that the document has passed Reader Claude testing. Before completion:
Ask whether they want one more review, or whether the work is finished.
If the user wants a final review, give it. Otherwise: Announce document completion. Provide some final tips:
Tone:
Handling deviations:
Context management:
Artifact management:
create_file to draft full sectionsstr_replace for all editsQuality over speed:
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.