@devries-cameron20 / composio Mirror · read-only / commits / d7b6e7eb3
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 18:30 UTC

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

## What Restores the two docs-prose skills that were dropped from the skill tree: - `good-docs-writing` — the house documentation style guide (Voice, Structure, Terminology, Punctuation, Code examples, Formatting), for drafting or revising docs prose. - `good-docs-audit` — the review process that audits a doc/README/prose block against that guide and reports `file:line` findings with concrete rewrites. Report-only by default. ## Why Both existed at `d17a268d` under `.claude/skills/` and were deleted in #3666 (`chore(agents): normalize repo guidance skills`), which renamed the rest of the tree into the current taxonomy but did not carry these two over. Nothing replaced them: there is no docs-voice guidance in the repo today, and `docs-decisions` covers docs-site mechanics (Fumadocs, changelogs, ADRs), not prose style. ## Shape of the restore Rule content is restored unchanged from `d17a268d`. Only the file layout differs, because the old flat single-file form no longer passes `validate:agent-skills` (SKILL.md is now capped at 80 lines and a linked `references/` directory is required): ``` .agents/skills/good-docs-writing/SKILL.md # routing + the rules that matter most .agents/skills/good-docs-writing/references/style-guide.md .agents/skills/good-docs-audit/SKILL.md # routing + non-negotiables .agents/skills/good-docs-audit/references/audit-process.md ``` They live under `.agents/skills` (canonical); `.claude/skills` is a symlink, so there is no second copy. Wiring, all three places the taxonomy is asserted: - `ts/scripts/validate-agent-skills.mjs` — added to the `expectedSkills` gate - `ts/scripts/test-skill-routing.mjs` — one routing probe each (the validator fails on any skill without a probe) - `AGENTS.md` — added to the Skill Routing list ## Test results - `node ts/scripts/test-skill-routing.mjs` — passes, 18 probes over 18 skills. Both new probes resolve to a unique top match. - `node ts/scripts/validate-agent-skills.mjs` — zero findings against tracked files. - `pnpm lint-staged` — no staged file matches a configured task (patterns cover `ts/packages/**` and `python/**`). - Markdown formatted with the repo Prettier config. Two notes on how those were run. `pnpm validate:*` could not be used locally: pnpm's pre-run dependency check tries to purge and reinstall the workspace and aborts without a TTY, so the scripts were invoked directly with `node` (same entrypoints the pnpm scripts use). Separately, `validate-agent-skills` reports stale-guidance hits under `docs/.eve/dev-runtime/snapshots/**` on my machine; those are untracked, gitignored local eve snapshots, unrelated to this change, and won't exist in CI. The commit used `--no-verify` because the pre-commit hook is just the `pnpm lint-staged` wrapper that hits the same pnpm abort; lint-staged was run manually instead. No changeset: guidance and tooling only, no published package touched. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Rahul Tarak committed Jul 30, 2026 at 05:31 UTC d7b6e7eb30e71aa5f9f570dc4f51c4af5ed4c2ee
7 files changed +192
.agents/skills/good-docs-audit/SKILL.md new
+17
@@ -0,0 +1,17 @@
1 +---
2 +name: good-docs-audit
3 +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.
4 +---
5 +
6 +# Good docs audit
7 +
8 +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.
9 +
10 +Read `references/audit-process.md` for the procedure, the prioritized violation checklist, the report format, and the reporting rules.
11 +
12 +Non-negotiables:
13 +
14 +- Read `good-docs-writing` (and its `references/style-guide.md`) first. Those rules are the rubric; this skill is the process.
15 +- Cite `file:line` for every finding and quote the exact offending text.
16 +- Give a real rewrite in the target voice, not "consider revising."
17 +- Don't invent violations. A short report is a good outcome.
.agents/skills/good-docs-audit/references/audit-process.md new
+65
@@ -0,0 +1,65 @@
1 +# Audit Process
2 +
3 +## Procedure
4 +
5 +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.
6 +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.
7 +3. **Walk each rule category** against the prose. Note every concrete violation with its line number.
8 +4. **Write the report** in the format below. Keep suggestions concrete: give the actual rewrite, not "consider revising."
9 +5. **Stop and present the report.** Offer to apply fixes; apply only if asked.
10 +
11 +## Prioritized checklist
12 +
13 +Scan for these in roughly this order. The top items most damage the voice:
14 +
15 +1. **Hedging & filler**: "it might be the case that," "in order to," "basically," "simply," "just." Cut or commit.
16 +2. **Passive voice** where active is clearer: "the function is invoked by the client" → "the client invokes the function."
17 +3. **Marketing fluff / vague intensifiers**: "seamlessly," "powerful," "robust," "blazing-fast," "cutting-edge," "world-class." Replace with a concrete claim or delete.
18 +4. **Em-dashes**: flag every em-dash; the house style bans them. Suggest a period, comma, colon, or parentheses in its place.
19 +5. **Third-person distance**: "the user," "one," "developers can" where "you" is meant.
20 +6. **Jargon without context**: an undefined acronym or term-of-art on first use with no grounding.
21 +7. **Inconsistent terminology**: the same concept named two ways, or core nouns (App, Function, Image, Volume, Secret) miscapitalized or capitalized inconsistently.
22 +8. **Title-case drift**: heading case that switches between sentence case and title case within one doc.
23 +9. **Missing backticks**: code identifiers, commands, params, paths, or filenames in plain text.
24 +10. **Buried warnings**: gotchas, version notes, or gated-feature notes in prose that should be callouts.
25 +11. **Weak openings**: page or section that doesn't lead with the concept or benefit; throat-clearing before the point.
26 +12. **Fragment / unrunnable code**: snippets that can't be pasted and run, or missing the expected-output / footgun note.
27 +
28 +## Report format
29 +
30 +Output a summary line, then findings grouped by severity. Each finding uses this shape:
31 +
32 +```
33 +- file.md:42 · [Punctuation] Em-dash banned
34 + Offending: "Modal is fast — really fast — and it scales automatically."
35 + Rewrite: "Modal is fast, really fast, and it scales automatically."
36 +```
37 +
38 +Structure the full report as:
39 +
40 +### Audit: <file or scope>
41 +
42 +**Summary:** <N findings: X high, Y medium, Z low. One-line verdict on overall voice fit.>
43 +
44 +**High** (breaks the voice / reader-facing clarity)
45 +
46 +- `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…"
47 +
48 +**Medium** (consistency and polish)
49 +
50 +- `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…"
51 +
52 +**Low** (nits)
53 +
54 +- `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…"
55 +
56 +**Patterns:** <recurring issues worth a global fix, e.g. "'the user' used 11x, switch to 'you' throughout.">
57 +
58 +## Rules
59 +
60 +- **Always cite `file:line`** so findings are actionable. Use the line numbers from your Read.
61 +- **Quote the exact offending text**; don't paraphrase the problem away.
62 +- **Give a real rewrite**, in the target voice, for every finding, not generic advice.
63 +- **Map each finding to a style-guide category** (Voice, Structure, Terminology, Punctuation, Code, Formatting) in brackets.
64 +- **Don't invent violations.** If the prose already matches the voice, say so. A short report is a good outcome.
65 +- **Don't edit by default.** Report, then offer to apply. Only write to files when explicitly asked.
.agents/skills/good-docs-writing/SKILL.md new
+21
@@ -0,0 +1,21 @@
1 +---
2 +name: good-docs-writing
3 +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.
4 +---
5 +
6 +# Good docs writing
7 +
8 +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.
9 +
10 +Read `references/style-guide.md` for the full rule set (Voice, Structure, Terminology, Punctuation, Code examples, Formatting) and apply every rule while drafting.
11 +
12 +The rules that matter most, before you open the reference:
13 +
14 +- Address the reader as "you", never "the user" or "one".
15 +- Open with the concept or benefit in the first sentence. No throat-clearing.
16 +- Put a minimal runnable example near the top, then explain what just happened.
17 +- Remove every em-dash. Use a period, comma, colon, or parentheses instead.
18 +- Cut vague intensifiers ("seamlessly", "powerful", "robust", "cutting-edge"). Show a thing being easy instead of calling it easy.
19 +- Backtick every code identifier, command, parameter, path, and filename.
20 +
21 +To review existing prose against these rules instead of drafting, use `good-docs-audit`.
.agents/skills/good-docs-writing/references/style-guide.md new
+75
@@ -0,0 +1,75 @@
1 +# Style Guide
2 +
3 +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).
4 +
5 +## Voice & Tone
6 +
7 +- **Address the reader as "you"; speak directly.** Don't hide behind "the user" or "one."
8 + > "Modal's goal is to make running code in the cloud feel like you're running code locally."
9 +- **Be confident and plain, not hedgy or salesy.** State what's true. Lead with the benefit, not the disclaimer.
10 + > "Modal makes it trivially easy to scale compute across thousands of containers."
11 +- **Reassure when something is automatic.** Tell the reader what they _don't_ have to worry about.
12 + > "For the most part, scaling out will happen automatically, and you won't need to think about it."
13 +- **Explain the "why" before prescribing the "how."** Motivate the solution, then give it.
14 +- **Use contractions naturally** ("you don't," "won't," "it's"). They keep the tone human.
15 +- **Allow occasional warmth and personality** ("That's it!", "Take a breath of fresh air"), sparingly, never goofy.
16 +
17 +## Structure
18 +
19 +- **Open by defining the concept or stating the benefit in one sentence**, then elaborate. No throat-clearing.
20 + > "An `App` represents an application running on Modal. It groups one or more Functions for atomic deployment and acts as a shared namespace."
21 +- **Order content as concept → simple example → advanced cases → gotchas.** Progressive disclosure.
22 +- **Lead with a minimal runnable example early**, then explain what just happened.
23 +- **Keep paragraphs short.** Break dense information into bullet lists and numbered steps.
24 +- **Use signposting transitions** to mark explanatory shifts: "What just happened?", "But why does this matter?", "Now, as before, …".
25 +- **Mix sentence lengths.** Short declarative sentences carry the load; longer ones add necessary nuance.
26 + > "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."
27 +
28 +## Terminology
29 +
30 +- **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.
31 +- **Name the product consistently**; never "the Modal platform" filler.
32 +- **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.
33 + > "This is known as a _cold start_, and it is often associated with higher latency."
34 +- **Avoid marketing fluff and vague intensifiers** ("seamlessly," "powerful," "robust," "cutting-edge"). If a thing is easy, show it being easy.
35 +- **Use analogies to ground unfamiliar concepts**, then move on.
36 + > "Containers are like light-weight virtual machines."
37 +
38 +## Punctuation
39 +
40 +- **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.)
41 +- **Use the Oxford comma.**
42 +- **Use backticks for every code identifier, command, parameter, path, and filename**: `@app.function()`, `modal deploy`, `scaledown_window`, `/gpu-glossary/`.
43 +- **Use italics for fine distinctions and negation**, not for general emphasis.
44 + > "This automatic upgrade does _not_ change the cost of the GPU."
45 +- **Capitalize acronyms and hardware names** as conventional: GPU, ASGI, A100, H100.
46 +
47 +## Code examples
48 +
49 +- **Show a complete, runnable snippet first**: imports, decorator, function, not a fragment the reader can't paste.
50 +- **Keep examples minimal.** Use simple names (`f`, `app`) and elide irrelevant bodies with `...`.
51 +- **Show the decorator pattern Modal uses** (`@app.function()`, `@app.cls()`) and method chaining for Images.
52 +- **Put comments only where behavior is non-obvious**; let clean code speak otherwise. Show expected output inline where it teaches something (`# 42`).
53 +- **Show real CLI invocation forms** with realistic prompts: `$ ` or `%` for shell, `>>>` for the Python REPL.
54 + > "modal run script.py::app.f"
55 +- **When a flag is a footgun, say so right after the example.**
56 + > "Remember to remove `force_build=True` after you've rebuilt the Image, or it will rebuild every time you run your code."
57 +
58 +## Formatting
59 +
60 +- **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.
61 +- **Prefer descriptive, specific headings** over generic ones: "Entrypoints for ephemeral Apps," not "Entrypoints."
62 +- **Use callouts for warnings, notes, gated features, and beta status** rather than burying them in prose.
63 + > "Deployment rollbacks are available on the Team and Enterprise plans."
64 +- **Correct gently with a "Note that …" or "Gotchas" aside** instead of stern warnings.
65 +- **Link with descriptive anchor text**, embedded naturally in the sentence, never a bare URL or "click here."
66 +- **Bold key concepts on first definition**, then stop bolding them.
67 +
68 +## Quick self-check while drafting
69 +
70 +- Did I open with the concept or benefit in the first sentence?
71 +- Is there a runnable example near the top?
72 +- Am I saying "you," not "the user"?
73 +- Did I remove every em-dash?
74 +- Did I cut every "seamlessly," "powerful," and other vague intensifier?
75 +- Are all code identifiers in backticks and core nouns (App, Function, Volume) capitalized?
AGENTS.md
+2
@@ -23,6 +23,8 @@ Use the smallest relevant skill:
23 - `bug-fixing`: fixing a defect and choosing regression tests.
24 - `cross-sdk-parity`: aligning TypeScript and Python behavior, generated client bumps, or API contract drift.
25 - `docs-decisions`: docs site work, changelogs, docs decisions, or docs automation.
26 +- `good-docs-writing`: drafting or revising docs prose in the house writing voice.
27 +- `good-docs-audit`: reviewing existing docs or prose against that voice and reporting violations.
28 - `eve`: durable backend AI agents built with the eve framework.
29 - `typescript-sdk`, `typescript-testing`, `typescript-providers`: TypeScript SDK/core/provider work.
30 - `cli-command`, `cli-e2e`: CLI design/implementation or CLI end-to-end tests.
ts/scripts/test-skill-routing.mjs
+10
@@ -72,6 +72,16 @@ const probes = [
72 expect: 'eve',
73 terms: ['durable backend AI agents', 'eve framework', 'channels', 'schedules'],
74 },
75 + {
76 + task: 'draft a new guide in the house documentation voice',
77 + expect: 'good-docs-writing',
78 + terms: ['writing style guide', "modal's documentation voice", 'second-person', 'example-first'],
79 + },
80 + {
81 + task: 'review a README for voice and tone violations and report suggested rewrites',
82 + expect: 'good-docs-audit',
83 + terms: ['report violations', 'critique', 'suggested rewrite', 'rule violated'],
84 + },
85 {
86 task: 'create a Python provider adapter under python/providers with metadata',
87 expect: 'python-providers',
ts/scripts/validate-agent-skills.mjs
+2
@@ -18,6 +18,8 @@ const expectedSkills = [
18 'cross-sdk-parity',
19 'docs-decisions',
20 'eve',
21 + 'good-docs-audit',
22 + 'good-docs-writing',
23 'python-providers',
24 'python-release',
25 'python-sdk',