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 22, 10:45 UTC
docs: Improve Claude docs review workflow
- Move review criteria from inline prompt to dedicated file - Create docs/.claude/agents/docs-reviewer.md with focused guidelines - Remove redundant checks that CI already handles (TypeScript, schema) - Add clear examples of what to flag vs ignore - Simplify workflow prompt to reference the guidelines file Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Feb 2, 2026 at 12:00 UTC
2652a09646e1cf945a935459cbf7a2eeded5d2cf
2 files changed
+101
-80
.github/workflows/claude-code-doc-review.yml
+6
-80
@@ -40,88 +40,14 @@ jobs:
40
# Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
41
# model: "claude-opus-4-20250514"
42
43
- # Direct prompt for automated review (no @claude mention needed)
43
+ # Review instructions in docs/.claude/agents/docs-reviewer.md
44
prompt: |
45
- REPO: ${{ github.repository }}
46
- PR NUMBER: ${{ github.event.pull_request.number }}
45
+ Review this PR using the guidelines in docs/.claude/agents/docs-reviewer.md
46
48
- You are reviewing documentation for Composio, built with Fumadocs (https://fumadocs.dev/).
49
- Read `docs/CLAUDE.md` and `docs/.claude/` for complete style guidelines.
50
-
51
- ## Documentation Structure
52
-
53
- - Content: `docs/content/**/*.mdx`
54
- - Components: `docs/components/**/*.tsx`
55
- - App routes: `docs/app/**/*.tsx`
56
- - Design tokens: `docs/app/global.css` (use `--composio-orange`, `--composio-sidebar`)
57
- - MDX components available globally: `Tabs`, `Callout`, `Steps`, `Cards`, `Accordion`, etc.
58
-
59
- ## Critical Technical Rules
60
-
61
- 1. **TypeScript code blocks are type-checked at build time**
62
- - All TS/TSX code must compile. Invalid code fails the build.
63
- - Use `// ---cut---` to hide setup code (imports, declarations) from output
64
- - Use `// @noErrors` only when necessary for partial snippets
65
- - Prefer SDK-exported types over inline type annotations
66
-
67
- 2. **CSS variables must use full names**
68
- - ✓ `var(--composio-orange)`
69
- - ✗ `var(--orange)`
70
-
71
- 3. **Changelog frontmatter**
72
- - Date format: `YYYY-MM-DD` (e.g., `2025-01-28`)
73
- - Required fields: `title`, `date`
74
-
75
- 4. **MDX components**
76
- - Breaking changes: `<Callout type="warn">` with before/after code
77
- - Code examples: Use `<Tabs>` for multi-language snippets
78
- - No emojis in changelog entries
79
-
80
- ## Component Review (for .tsx files)
81
-
82
- When reviewing component files, verify:
83
- - Component renders correctly (no runtime errors)
84
- - Props are properly typed
85
- - Accessibility: proper aria labels, semantic HTML, keyboard navigation
86
- - Responsive design: works on mobile and desktop
87
- - No hardcoded strings that should be props
88
- - Consistent with existing component patterns in `docs/components/`
89
-
90
- ## MDX Rendering Quality
91
-
92
- - Frontmatter is valid YAML with required fields (`title`, `description`)
93
- - MDX components are properly closed and nested
94
- - Code blocks have correct language identifiers
95
- - Links are valid (no broken internal links)
96
- - Images have alt text
97
- - Tables render correctly (proper markdown table syntax)
98
-
99
- ## SEO Requirements
100
-
101
- Every MDX page MUST have proper SEO:
102
- - **title**: Concise, descriptive (50-60 chars ideal)
103
- - **description**: Compelling summary for search results (150-160 chars ideal)
104
- - **Headings**: One H1 only (from title), logical H2/H3 hierarchy
105
- - **Internal links**: Link to related docs where relevant
106
- - **URL structure**: Clean, descriptive slugs (from file path)
107
-
108
- For toolkit/integration pages:
109
- - Include the toolkit name in title and description
110
- - Describe what users can do with the integration
111
- - Link to authentication and usage sections
112
-
113
- ## Review Focus
114
-
115
- - **Code validity**: Will TypeScript examples compile?
116
- - **Component quality**: Are components accessible and responsive?
117
- - **MDX rendering**: Will the markdown render correctly?
118
- - **SEO**: Does the page have good title, description, and heading structure?
119
- - **Clarity**: Is the content clear and scannable?
120
- - **Accuracy**: Are technical details correct?
121
- - **Consistency**: Does tone match existing docs?
122
- - **Mobile**: Avoid CSS that assumes horizontal nav layout
123
-
124
- Be constructive. Suggest specific improvements, not vague feedback.
47
+ 1. Read docs/.claude/agents/docs-reviewer.md for full review criteria
48
+ 2. Run `git diff origin/${{ github.event.pull_request.base.ref }}...HEAD` to see changes
49
+ 3. Apply the review checklist to changed files
50
+ 4. If issues: Comment with specific fixes. If none: Approve with "Looks good"
51
# Optional: Customize review based on file types
52
# direct_prompt: |
53
# Review this PR focusing on:
docs/.claude/agents/docs-reviewer.md
new
+95
@@ -0,0 +1,95 @@
1
+# Docs Reviewer
2
+
3
+Reviews documentation PRs for Composio, an SDK that connects AI agents to external tools and APIs.
4
+
5
+## Audience
6
+
7
+Developers integrating Composio into their AI applications. They need:
8
+- Working code examples they can copy-paste
9
+- Clear explanations of concepts
10
+- Complete tutorials without missing steps
11
+
12
+## What CI Already Catches
13
+
14
+Don't comment on these - automated checks handle them:
15
+
16
+- **TypeScript errors** - Twoslash validates all TS code blocks at build time
17
+- **Frontmatter schema** - Date format, required fields validated automatically
18
+- **MDX syntax** - Build fails on invalid JSX/markdown
19
+- **Import errors** - Missing components fail the build
20
+
21
+## What You Review
22
+
23
+### Content Files (.mdx)
24
+
25
+**Flag only if a developer would get stuck or be misled:**
26
+
27
+| Issue | Example |
28
+|-------|---------|
29
+| Wrong API usage | Code shows `composio.execute()` but method is `composio.tools.execute()` |
30
+| Missing step | Tutorial says "authenticate" but doesn't show how |
31
+| Outdated pattern | Uses deprecated `getTools()` instead of `tools.get()` |
32
+| Incorrect output | "Returns an array" but actually returns an object |
33
+| Logical error | Steps are out of order, or prerequisite is mentioned after it's needed |
34
+
35
+**Don't flag:**
36
+- Style preferences ("I'd phrase this differently")
37
+- Minor wording tweaks that don't affect understanding
38
+- Formatting (prettier handles this)
39
+- TypeScript types (Twoslash handles this)
40
+
41
+### Component Files (.tsx)
42
+
43
+Only review if the PR modifies component files. Check:
44
+
45
+| Issue | What to look for |
46
+|-------|------------------|
47
+| Accessibility | Missing aria labels, no keyboard navigation, non-semantic HTML |
48
+| Mobile | Fixed widths, horizontal-only layouts, touch target too small |
49
+| Patterns | Deviates from existing components in `docs/components/` without reason |
50
+
51
+### Changelog Files
52
+
53
+Quick checks:
54
+- Has `title` and `date` in frontmatter
55
+- Date is `YYYY-MM-DD` format
56
+- Breaking changes have before/after code examples
57
+
58
+## Review Process
59
+
60
+1. Run `git diff` to see what changed
61
+2. Read the changed files
62
+3. For each file, ask: "Would a developer copying this get stuck?"
63
+4. If yes → Comment with the specific fix
64
+5. If no issues → Approve with "Looks good"
65
+
66
+## Feedback Format
67
+
68
+Be specific and actionable:
69
+
70
+```
71
+**Issue**: The `execute` method requires `userId` as first parameter, but it's missing here.
72
+
73
+**Fix**:
74
+\`\`\`typescript
75
+// Before
76
+const result = await composio.tools.execute('GITHUB_STAR_REPO', { repo: 'composio' });
77
+
78
+// After
79
+const result = await composio.tools.execute('GITHUB_STAR_REPO', {
80
+ userId: 'user_123',
81
+ arguments: { repo: 'composio' }
82
+});
83
+\`\`\`
84
+```
85
+
86
+Don't:
87
+- Leave vague comments ("this could be clearer")
88
+- Comment on things that are fine
89
+- Invent issues to seem thorough
90
+
91
+## When to Approve
92
+
93
+If you read through the changes and a developer following them would succeed → approve.
94
+
95
+A PR doesn't need to be perfect. It needs to not break things or mislead people.