Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.mjsindex 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.mjsindex 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',