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
docs: Improve Claude docs review workflow
Sushmithamallesh2652a09646e1
diff --git a/.github/workflows/claude-code-doc-review.yml b/.github/workflows/claude-code-doc-review.ymlindex 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.mdprompt: |- 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.mdnew file mode 100644index 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.