Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

chore(agents): restore good-docs-writing and good-docs-audit skills (#3991)

Rahul Tarakd7b6e7eb30e7
diff --git a/.agents/skills/good-docs-audit/SKILL.md b/.agents/skills/good-docs-audit/SKILL.md
new file mode 100644
index 000000000..14ff3d750
--- /dev/null
+++ b/.agents/skills/good-docs-audit/SKILL.md
@@ -0,0 +1,17 @@
+---
+name: good-docs-audit
+description: Audit a doc, guide, README, or block of prose against the good-docs-writing style guide and report violations. Use when the user asks to review, critique, lint, or check the voice and tone of documentation or text. Produces a structured findings report (file:line, rule violated, offending text, suggested rewrite) and does NOT edit files unless explicitly asked.
+---
+
+# Good docs audit
+
+Review target documentation against the `good-docs-writing` rules and report where the writing drifts from that voice. Default behavior is **report only**: produce findings, do not edit. Only modify files if the user explicitly says to fix, rewrite, or apply.
+
+Read `references/audit-process.md` for the procedure, the prioritized violation checklist, the report format, and the reporting rules.
+
+Non-negotiables:
+
+- Read `good-docs-writing` (and its `references/style-guide.md`) first. Those rules are the rubric; this skill is the process.
+- Cite `file:line` for every finding and quote the exact offending text.
+- Give a real rewrite in the target voice, not "consider revising."
+- Don't invent violations. A short report is a good outcome.
diff --git a/.agents/skills/good-docs-audit/references/audit-process.md b/.agents/skills/good-docs-audit/references/audit-process.md
new file mode 100644
index 000000000..a4a3daedd
--- /dev/null
+++ b/.agents/skills/good-docs-audit/references/audit-process.md
@@ -0,0 +1,65 @@
+# Audit Process
+
+## Procedure
+
+1. **Read the `good-docs-writing` skill 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.
+2. **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.
+3. **Walk each rule category** against the prose. Note every concrete violation with its line number.
+4. **Write the report** in the format below. Keep suggestions concrete: give the actual rewrite, not "consider revising."
+5. **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:
+
+1. **Hedging & filler**: "it might be the case that," "in order to," "basically," "simply," "just." Cut or commit.
+2. **Passive voice** where active is clearer: "the function is invoked by the client" → "the client invokes the function."
+3. **Marketing fluff / vague intensifiers**: "seamlessly," "powerful," "robust," "blazing-fast," "cutting-edge," "world-class." Replace with a concrete claim or delete.
+4. **Em-dashes**: flag every em-dash; the house style bans them. Suggest a period, comma, colon, or parentheses in its place.
+5. **Third-person distance**: "the user," "one," "developers can" where "you" is meant.
+6. **Jargon without context**: an undefined acronym or term-of-art on first use with no grounding.
+7. **Inconsistent terminology**: the same concept named two ways, or core nouns (App, Function, Image, Volume, Secret) miscapitalized or capitalized inconsistently.
+8. **Title-case drift**: heading case that switches between sentence case and title case within one doc.
+9. **Missing backticks**: code identifiers, commands, params, paths, or filenames in plain text.
+10. **Buried warnings**: gotchas, version notes, or gated-feature notes in prose that should be callouts.
+11. **Weak openings**: page or section that doesn't lead with the concept or benefit; throat-clearing before the point.
+12. **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: <file or scope>
+
+**Summary:** <N findings: X high, Y medium, Z low. One-line verdict on overall voice fit.>
+
+**High** (breaks the voice / reader-facing clarity)
+
+- `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…"
+
+**Medium** (consistency and polish)
+
+- `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…"
+
+**Low** (nits)
+
+- `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…"
+
+**Patterns:** <recurring issues worth a global fix, e.g. "'the user' used 11x, switch to 'you' throughout.">
+
+## Rules
+
+- **Always cite `file:line`** so 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.
diff --git a/.agents/skills/good-docs-writing/SKILL.md b/.agents/skills/good-docs-writing/SKILL.md
new file mode 100644
index 000000000..5d09d5753
--- /dev/null
+++ b/.agents/skills/good-docs-writing/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: good-docs-writing
+description: Writing style guide derived from Modal's documentation voice. Apply when writing or editing docs, guides, tutorials, or technical prose that should read direct, second-person, confident, low-jargon, and example-first. Use to draft new docs in this voice or to revise existing prose toward it.
+---
+
+# Good docs writing
+
+Write docs the way Modal writes them: direct, friendly, confident, and ruthlessly practical. Explain the _why_ in one breath, then show working code. Treat the reader as a capable developer who wants to ship, not a student who needs a lecture.
+
+Read `references/style-guide.md` for the full rule set (Voice, Structure, Terminology, Punctuation, Code examples, Formatting) and apply every rule while drafting.
+
+The rules that matter most, before you open the reference:
+
+- Address the reader as "you", never "the user" or "one".
+- Open with the concept or benefit in the first sentence. No throat-clearing.
+- Put a minimal runnable example near the top, then explain what just happened.
+- Remove every em-dash. Use a period, comma, colon, or parentheses instead.
+- Cut vague intensifiers ("seamlessly", "powerful", "robust", "cutting-edge"). Show a thing being easy instead of calling it easy.
+- Backtick every code identifier, command, parameter, path, and filename.
+
+To review existing prose against these rules instead of drafting, use `good-docs-audit`.
diff --git a/.agents/skills/good-docs-writing/references/style-guide.md b/.agents/skills/good-docs-writing/references/style-guide.md
new file mode 100644
index 000000000..7ad490fcb
--- /dev/null
+++ b/.agents/skills/good-docs-writing/references/style-guide.md
@@ -0,0 +1,75 @@
+# Style Guide
+
+Apply every rule below while drafting. Each rule is an imperative followed by a real Modal example as evidence (this guide is derived from Modal's documentation voice).
+
+## Voice & Tone
+
+- **Address the reader as "you"; speak directly.** Don't hide behind "the user" or "one."
+ > "Modal's goal is to make running code in the cloud feel like you're running code locally."
+- **Be confident and plain, not hedgy or salesy.** State what's true. Lead with the benefit, not the disclaimer.
+ > "Modal makes it trivially easy to scale compute across thousands of containers."
+- **Reassure when something is automatic.** Tell the reader what they _don't_ have to worry about.
+ > "For the most part, scaling out will happen automatically, and you won't need to think about it."
+- **Explain the "why" before prescribing the "how."** Motivate the solution, then give it.
+- **Use contractions naturally** ("you don't," "won't," "it's"). They keep the tone human.
+- **Allow occasional warmth and personality** ("That's it!", "Take a breath of fresh air"), sparingly, never goofy.
+
+## Structure
+
+- **Open by defining the concept or stating the benefit in one sentence**, then elaborate. No throat-clearing.
+ > "An `App` represents an application running on Modal. It groups one or more Functions for atomic deployment and acts as a shared namespace."
+- **Order content as concept → simple example → advanced cases → gotchas.** Progressive disclosure.
+- **Lead with a minimal runnable example early**, then explain what just happened.
+- **Keep paragraphs short.** Break dense information into bullet lists and numbered steps.
+- **Use signposting transitions** to mark explanatory shifts: "What just happened?", "But why does this matter?", "Now, as before, …".
+- **Mix sentence lengths.** Short declarative sentences carry the load; longer ones add necessary nuance.
+ > "The timeout duration is a measure of a Function's _execution_ time. It does not include scheduling time or any other period besides the time your code is executing in Modal."
+
+## Terminology
+
+- **Capitalize your product's core nouns as proper concepts** the way Modal capitalizes App, Function, Image, Volume, Secret, Sandbox, Cls. Capitalize a noun when it names the product, lowercase for the generic idea.
+- **Name the product consistently**; never "the Modal platform" filler.
+- **Prefer precise technical terms over hand-waving**: "cold start," "autoscaler," "ephemeral," "atomic deployment," "warm pool," "scaledown window." Introduce a term in context the first time, then use it freely.
+ > "This is known as a _cold start_, and it is often associated with higher latency."
+- **Avoid marketing fluff and vague intensifiers** ("seamlessly," "powerful," "robust," "cutting-edge"). If a thing is easy, show it being easy.
+- **Use analogies to ground unfamiliar concepts**, then move on.
+ > "Containers are like light-weight virtual machines."
+
+## Punctuation
+
+- **Do not use em-dashes.** Rewrite the sentence with a period, comma, colon, or parentheses instead. This is a hard rule; remove every em-dash before you ship. (This overrides Modal's softer "em-dashes for genuine asides only" guidance: em-dashes are banned here.)
+- **Use the Oxford comma.**
+- **Use backticks for every code identifier, command, parameter, path, and filename**: `@app.function()`, `modal deploy`, `scaledown_window`, `/gpu-glossary/`.
+- **Use italics for fine distinctions and negation**, not for general emphasis.
+ > "This automatic upgrade does _not_ change the cost of the GPU."
+- **Capitalize acronyms and hardware names** as conventional: GPU, ASGI, A100, H100.
+
+## Code examples
+
+- **Show a complete, runnable snippet first**: imports, decorator, function, not a fragment the reader can't paste.
+- **Keep examples minimal.** Use simple names (`f`, `app`) and elide irrelevant bodies with `...`.
+- **Show the decorator pattern Modal uses** (`@app.function()`, `@app.cls()`) and method chaining for Images.
+- **Put comments only where behavior is non-obvious**; let clean code speak otherwise. Show expected output inline where it teaches something (`# 42`).
+- **Show real CLI invocation forms** with realistic prompts: `$ ` or `%` for shell, `>>>` for the Python REPL.
+ > "modal run script.py::app.f"
+- **When a flag is a footgun, say so right after the example.**
+ > "Remember to remove `force_build=True` after you've rebuilt the Image, or it will rebuild every time you run your code."
+
+## Formatting
+
+- **Use heading case consistently within a doc.** Modal leans toward sentence case for conceptual guides ("How do Web Functions run in the cloud?", "Scaling out") and title case for reference-style headings ("Volume commits and reloads"). Pick one convention per page and don't drift.
+- **Prefer descriptive, specific headings** over generic ones: "Entrypoints for ephemeral Apps," not "Entrypoints."
+- **Use callouts for warnings, notes, gated features, and beta status** rather than burying them in prose.
+ > "Deployment rollbacks are available on the Team and Enterprise plans."
+- **Correct gently with a "Note that …" or "Gotchas" aside** instead of stern warnings.
+- **Link with descriptive anchor text**, embedded naturally in the sentence, never a bare URL or "click here."
+- **Bold key concepts on first definition**, then stop bolding them.
+
+## Quick self-check while drafting
+
+- Did I open with the concept or benefit in the first sentence?
+- Is there a runnable example near the top?
+- Am I saying "you," not "the user"?
+- Did I remove every em-dash?
+- Did I cut every "seamlessly," "powerful," and other vague intensifier?
+- Are all code identifiers in backticks and core nouns (App, Function, Volume) capitalized?
diff --git a/AGENTS.md b/AGENTS.md
index 4c9949271..c12610945 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,8 @@ Use the smallest relevant skill:
- `bug-fixing`: fixing a defect and choosing regression tests.
- `cross-sdk-parity`: aligning TypeScript and Python behavior, generated client bumps, or API contract drift.
- `docs-decisions`: docs site work, changelogs, docs decisions, or docs automation.
+- `good-docs-writing`: drafting or revising docs prose in the house writing voice.
+- `good-docs-audit`: reviewing existing docs or prose against that voice and reporting violations.
- `eve`: durable backend AI agents built with the eve framework.
- `typescript-sdk`, `typescript-testing`, `typescript-providers`: TypeScript SDK/core/provider work.
- `cli-command`, `cli-e2e`: CLI design/implementation or CLI end-to-end tests.
diff --git a/ts/scripts/test-skill-routing.mjs b/ts/scripts/test-skill-routing.mjs
index 6639bda15..057baae9d 100644
--- a/ts/scripts/test-skill-routing.mjs
+++ b/ts/scripts/test-skill-routing.mjs
@@ -72,6 +72,16 @@ const probes = [
expect: 'eve',
terms: ['durable backend AI agents', 'eve framework', 'channels', 'schedules'],
},
+ {
+ task: 'draft a new guide in the house documentation voice',
+ expect: 'good-docs-writing',
+ terms: ['writing style guide', "modal's documentation voice", 'second-person', 'example-first'],
+ },
+ {
+ task: 'review a README for voice and tone violations and report suggested rewrites',
+ expect: 'good-docs-audit',
+ terms: ['report violations', 'critique', 'suggested rewrite', 'rule violated'],
+ },
{
task: 'create a Python provider adapter under python/providers with metadata',
expect: 'python-providers',
diff --git a/ts/scripts/validate-agent-skills.mjs b/ts/scripts/validate-agent-skills.mjs
index b6310639f..2350803bd 100644
--- a/ts/scripts/validate-agent-skills.mjs
+++ b/ts/scripts/validate-agent-skills.mjs
@@ -18,6 +18,8 @@ const expectedSkills = [
'cross-sdk-parity',
'docs-decisions',
'eve',
+ 'good-docs-audit',
+ 'good-docs-writing',
'python-providers',
'python-release',
'python-sdk',