Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Audit Process
Procedure
- Read the
good-docs-writingskill first so you audit against its current rules (Voice, Structure, Terminology, Punctuation, Code examples, Formatting). Those rules are the rubric; this skill is the process. - Read the target file(s) in full with line numbers. If the user named a directory or glob, enumerate the docs and audit each. If no target is given, ask which file(s) to audit.
- Walk each rule category against the prose. Note every concrete violation with its line number.
- Write the report in the format below. Keep suggestions concrete: give the actual rewrite, not "consider revising."
- Stop and present the report. Offer to apply fixes; apply only if asked.
Prioritized checklist
Scan for these in roughly this order. The top items most damage the voice:
- Hedging & filler: "it might be the case that," "in order to," "basically," "simply," "just." Cut or commit.
- Passive voice where active is clearer: "the function is invoked by the client" → "the client invokes the function."
- Marketing fluff / vague intensifiers: "seamlessly," "powerful," "robust," "blazing-fast," "cutting-edge," "world-class." Replace with a concrete claim or delete.
- Em-dashes: flag every em-dash; the house style bans them. Suggest a period, comma, colon, or parentheses in its place.
- Third-person distance: "the user," "one," "developers can" where "you" is meant.
- Jargon without context: an undefined acronym or term-of-art on first use with no grounding.
- Inconsistent terminology: the same concept named two ways, or core nouns (App, Function, Image, Volume, Secret) miscapitalized or capitalized inconsistently.
- Title-case drift: heading case that switches between sentence case and title case within one doc.
- Missing backticks: code identifiers, commands, params, paths, or filenames in plain text.
- Buried warnings: gotchas, version notes, or gated-feature notes in prose that should be callouts.
- Weak openings: page or section that doesn't lead with the concept or benefit; throat-clearing before the point.
- Fragment / unrunnable code: snippets that can't be pasted and run, or missing the expected-output / footgun note.
Report format
Output a summary line, then findings grouped by severity. Each finding uses this shape:
- file.md:42 · [Punctuation] Em-dash banned
Offending: "Modal is fast — really fast — and it scales automatically."
Rewrite: "Modal is fast, really fast, and it scales automatically."
Structure the full report as:
Audit:
Summary:
High (breaks the voice / reader-facing clarity)
path:line· [Category] · Offending: "…" · Rewrite: "…"
Medium (consistency and polish)
path:line· [Category] · Offending: "…" · Rewrite: "…"
Low (nits)
path:line· [Category] · Offending: "…" · Rewrite: "…"
Patterns:
Rules
- Always cite
file:lineso findings are actionable. Use the line numbers from your Read. - Quote the exact offending text; don't paraphrase the problem away.
- Give a real rewrite, in the target voice, for every finding, not generic advice.
- Map each finding to a style-guide category (Voice, Structure, Terminology, Punctuation, Code, Formatting) in brackets.
- Don't invent violations. If the prose already matches the voice, say so. A short report is a good outcome.
- Don't edit by default. Report, then offer to apply. Only write to files when explicitly asked.