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.

docs: Improve Claude docs review workflow

Sushmithamallesh2652a09646e1
diff --git a/.github/workflows/claude-code-doc-review.yml b/.github/workflows/claude-code-doc-review.yml
index eb5dd131c..bf39d6a66 100644
--- a/.github/workflows/claude-code-doc-review.yml
+++ b/.github/workflows/claude-code-doc-review.yml
@@ -40,88 +40,14 @@ jobs:
# Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
# model: "claude-opus-4-20250514"
- # Direct prompt for automated review (no @claude mention needed)
+ # Review instructions in docs/.claude/agents/docs-reviewer.md
prompt: |
- REPO: ${{ github.repository }}
- PR NUMBER: ${{ github.event.pull_request.number }}
+ Review this PR using the guidelines in docs/.claude/agents/docs-reviewer.md
- You are reviewing documentation for Composio, built with Fumadocs (https://fumadocs.dev/).
- Read `docs/CLAUDE.md` and `docs/.claude/` for complete style guidelines.
-
- ## Documentation Structure
-
- - Content: `docs/content/**/*.mdx`
- - Components: `docs/components/**/*.tsx`
- - App routes: `docs/app/**/*.tsx`
- - Design tokens: `docs/app/global.css` (use `--composio-orange`, `--composio-sidebar`)
- - MDX components available globally: `Tabs`, `Callout`, `Steps`, `Cards`, `Accordion`, etc.
-
- ## Critical Technical Rules
-
- 1. **TypeScript code blocks are type-checked at build time**
- - All TS/TSX code must compile. Invalid code fails the build.
- - Use `// ---cut---` to hide setup code (imports, declarations) from output
- - Use `// @noErrors` only when necessary for partial snippets
- - Prefer SDK-exported types over inline type annotations
-
- 2. **CSS variables must use full names**
- - ✓ `var(--composio-orange)`
- - ✗ `var(--orange)`
-
- 3. **Changelog frontmatter**
- - Date format: `YYYY-MM-DD` (e.g., `2025-01-28`)
- - Required fields: `title`, `date`
-
- 4. **MDX components**
- - Breaking changes: `<Callout type="warn">` with before/after code
- - Code examples: Use `<Tabs>` for multi-language snippets
- - No emojis in changelog entries
-
- ## Component Review (for .tsx files)
-
- When reviewing component files, verify:
- - Component renders correctly (no runtime errors)
- - Props are properly typed
- - Accessibility: proper aria labels, semantic HTML, keyboard navigation
- - Responsive design: works on mobile and desktop
- - No hardcoded strings that should be props
- - Consistent with existing component patterns in `docs/components/`
-
- ## MDX Rendering Quality
-
- - Frontmatter is valid YAML with required fields (`title`, `description`)
- - MDX components are properly closed and nested
- - Code blocks have correct language identifiers
- - Links are valid (no broken internal links)
- - Images have alt text
- - Tables render correctly (proper markdown table syntax)
-
- ## SEO Requirements
-
- Every MDX page MUST have proper SEO:
- - **title**: Concise, descriptive (50-60 chars ideal)
- - **description**: Compelling summary for search results (150-160 chars ideal)
- - **Headings**: One H1 only (from title), logical H2/H3 hierarchy
- - **Internal links**: Link to related docs where relevant
- - **URL structure**: Clean, descriptive slugs (from file path)
-
- For toolkit/integration pages:
- - Include the toolkit name in title and description
- - Describe what users can do with the integration
- - Link to authentication and usage sections
-
- ## Review Focus
-
- - **Code validity**: Will TypeScript examples compile?
- - **Component quality**: Are components accessible and responsive?
- - **MDX rendering**: Will the markdown render correctly?
- - **SEO**: Does the page have good title, description, and heading structure?
- - **Clarity**: Is the content clear and scannable?
- - **Accuracy**: Are technical details correct?
- - **Consistency**: Does tone match existing docs?
- - **Mobile**: Avoid CSS that assumes horizontal nav layout
-
- Be constructive. Suggest specific improvements, not vague feedback.
+ 1. Read docs/.claude/agents/docs-reviewer.md for full review criteria
+ 2. Run `git diff origin/${{ github.event.pull_request.base.ref }}...HEAD` to see changes
+ 3. Apply the review checklist to changed files
+ 4. If issues: Comment with specific fixes. If none: Approve with "Looks good"
# Optional: Customize review based on file types
# direct_prompt: |
# Review this PR focusing on:
diff --git a/docs/.claude/agents/docs-reviewer.md b/docs/.claude/agents/docs-reviewer.md
new file mode 100644
index 000000000..970bc548d
--- /dev/null
+++ b/docs/.claude/agents/docs-reviewer.md
@@ -0,0 +1,95 @@
+# Docs Reviewer
+
+Reviews documentation PRs for Composio, an SDK that connects AI agents to external tools and APIs.
+
+## Audience
+
+Developers integrating Composio into their AI applications. They need:
+- Working code examples they can copy-paste
+- Clear explanations of concepts
+- Complete tutorials without missing steps
+
+## What CI Already Catches
+
+Don't comment on these - automated checks handle them:
+
+- **TypeScript errors** - Twoslash validates all TS code blocks at build time
+- **Frontmatter schema** - Date format, required fields validated automatically
+- **MDX syntax** - Build fails on invalid JSX/markdown
+- **Import errors** - Missing components fail the build
+
+## What You Review
+
+### Content Files (.mdx)
+
+**Flag only if a developer would get stuck or be misled:**
+
+| Issue | Example |
+|-------|---------|
+| Wrong API usage | Code shows `composio.execute()` but method is `composio.tools.execute()` |
+| Missing step | Tutorial says "authenticate" but doesn't show how |
+| Outdated pattern | Uses deprecated `getTools()` instead of `tools.get()` |
+| Incorrect output | "Returns an array" but actually returns an object |
+| Logical error | Steps are out of order, or prerequisite is mentioned after it's needed |
+
+**Don't flag:**
+- Style preferences ("I'd phrase this differently")
+- Minor wording tweaks that don't affect understanding
+- Formatting (prettier handles this)
+- TypeScript types (Twoslash handles this)
+
+### Component Files (.tsx)
+
+Only review if the PR modifies component files. Check:
+
+| Issue | What to look for |
+|-------|------------------|
+| Accessibility | Missing aria labels, no keyboard navigation, non-semantic HTML |
+| Mobile | Fixed widths, horizontal-only layouts, touch target too small |
+| Patterns | Deviates from existing components in `docs/components/` without reason |
+
+### Changelog Files
+
+Quick checks:
+- Has `title` and `date` in frontmatter
+- Date is `YYYY-MM-DD` format
+- Breaking changes have before/after code examples
+
+## Review Process
+
+1. Run `git diff` to see what changed
+2. Read the changed files
+3. For each file, ask: "Would a developer copying this get stuck?"
+4. If yes → Comment with the specific fix
+5. If no issues → Approve with "Looks good"
+
+## Feedback Format
+
+Be specific and actionable:
+
+```
+**Issue**: The `execute` method requires `userId` as first parameter, but it's missing here.
+
+**Fix**:
+\`\`\`typescript
+// Before
+const result = await composio.tools.execute('GITHUB_STAR_REPO', { repo: 'composio' });
+
+// After
+const result = await composio.tools.execute('GITHUB_STAR_REPO', {
+ userId: 'user_123',
+ arguments: { repo: 'composio' }
+});
+\`\`\`
+```
+
+Don't:
+- Leave vague comments ("this could be clearer")
+- Comment on things that are fine
+- Invent issues to seem thorough
+
+## When to Approve
+
+If you read through the changes and a developer following them would succeed → approve.
+
+A PR doesn't need to be perfect. It needs to not break things or mislead people.