claude-code-showcase

# Claude Code Project Configuration > Skill by [ara.so](https://ara.so) — Claude Code Skills collection. ## What This Project Does `claude-code-showcase` provides a comprehensive reference for configuring Claude Code projects with: - **Skills** - Domain knowledge documents that teach Claude your patterns (testing, GraphQL, UI components, etc.) - **Agents** - Specialized AI assistants that run automatically (code reviewers, ticket handlers) - **Hooks** - Scripts that run at key points (auto-format, run tests, block main branch edits) - **Commands** - Custom slash commands for common workflows (`/onboard`, `/pr-review`, `/ticket`) - **MCP Servers** - External integrations (JIRA, GitHub, Slack, databases) - **GitHub Actions** - Scheduled automation (docs sync, quality reviews, dependency audits) ## Installation & Setup ### 1. Initialize Claude Code Directory ```bash mkdir -p .claude/{agents,commands,hooks,skills,rules} touch .claude/settings.json touch CLAUDE.md ``` ### 2. Add Project Memory (CLAUDE.md) Create `CLAUDE.md` in your project root: ```markdown # My Project ## Stack - React 18, TypeScript 5.x, Node.js 20+ - GraphQL API (Apollo Client/Server) - Testing: Jest + React Testing Library ## Key Commands - `npm test` - Run tests - `npm run lint` - ESLint - `npm run typecheck` - TypeScript validation - `npm run build` - Production build ## Code Style - TypeScript strict mode enabled - Prefer interfaces over types - No `any` - use `unknown` instead - Components must handle loading/error states ## Key Directories - `src/components/` - React components - `src/api/` - GraphQL schema and resolvers - `src/hooks/` - Custom React hooks - `tests/` - Test files (colocated with source) ``` ### 3. Configure Settings & Hooks Create `.claude/settings.json`: ```json { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit files on main branch. Create a feature branch first.\"}' >&2; exit 2; }", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npx prettier --write {{file}}", "timeout": 10, "suppressOutput": true } ] }, { "matcher": "Edit.*\\.test\\.(ts|tsx|js|jsx)", "hooks": [ { "type": "command", "command": "npm test -- --findRelatedTests {{file}} --passWithNoTests", "timeout": 60 } ] } ], "UserPromptSubmit": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": ".claude/hooks/skill-eval.sh", "timeout": 5 } ] } ] }, "allowedCommands": [ "npm", "npx", "git", "node", "cat", "grep", "find" ], "environment": { "NODE_ENV": "development" } } ``` ## Creating Skills Skills are domain knowledge documents that teach Claude your patterns and conventions. ### Skill File Structure ``` .claude/skills/ ├── README.md ├── testing-patterns/ │ └── SKILL.md ├── graphql-schema/ │ └── SKILL.md └── core-components/ └── SKILL.md ``` ### Example: Testing Patterns Skill `.claude/skills/testing-patterns/SKILL.md`: ```markdown --- name: testing-patterns description: Jest and React Testing Library patterns for this project. Use when writing tests, creating mocks, or following TDD workflow. --- # Testing Patterns ## Test Structure Use the AAA pattern (Arrange, Act, Assert): \`\`\`typescript import { render, screen, waitFor } from '@testing-library/react'; import { userEvent } from '@testing-library/user-event'; describe('LoginForm', () => { it('submits credentials when form is valid', async () => { // Arrange const mockOnSubmit = jest.fn(); render(<LoginForm onSubmit={mockOnSubmit} />); // Act await userEvent.type(screen.getByLabelText(/email/i), 'user@example.com'); await userEvent.type(screen.getByLabelText(/password/i), 'password123'); await userEvent.click(screen.getByRole('button', { name: /sign in/i })); // Assert await waitFor(() => { expect(mockOnSubmit).toHaveBeenCalledWith({ email: 'user@example.com', password: 'password123' }); }); }); }); \`\`\` ## Mock Factories Create factory functions for reusable mocks: \`\`\`typescript // tests/factories/user.ts export const getMockUser = (overrides = {}) => ({ id: '123', email: 'test@example.com', name: 'Test User', role: 'user', ...overrides }); \`\`\` ## GraphQL Mocking Use MSW for GraphQL mocks: \`\`\`typescript import { graphql } from 'msw'; import { setupServer } from 'msw/node'; const server = setupServer( graphql.query('GetUser', (req, res, ctx) => { return res( ctx.data({ user: getMockUser() }) ); }) ); beforeAll(() => server.listen()); afterEach(() => server.resetHandlers()); afterAll(() => server.close()); \`\`\` ## Coverage Requirements - All components must have tests - Minimum 80% coverage for new code - Test happy path + error states + loading states ``` ### Example: GraphQL Schema Skill `.claude/skills/graphql-schema/SKILL.md`: ```markdown --- name: graphql-schema description: GraphQL schema design patterns and resolver conventions for this project. Use when creating types, queries, mutations, or resolvers. --- # GraphQL Schema Patterns ## Type Definitions \`\`\`graphql type User { id: ID! email: String! name: String! createdAt: DateTime! updatedAt: DateTime! } input CreateUserInput { email: String! name: String! password: String! } type CreateUserPayload { user: User errors: [UserError!] } \`\`\` ## Resolver Pattern \`\`\`typescript // src/api/resolvers/user.ts import { GraphQLError } from 'graphql'; export const userResolvers = { Query: { user: async (_, { id }, { dataSources, user }) => { if (!user) { throw new GraphQLError('Not authenticated', { extensions: { code: 'UNAUTHENTICATED' } }); } return dataSources.userAPI.getUser(id); } }, Mutation: { createUser: async (_, { input }, { dataSources }) => { try { const user = await dataSources.userAPI.createUser(input); return { user, errors: [] }; } catch (error) { return { user: null, errors: [{ message: error.message, field: 'email' }] }; } } } }; \`\`\` ## Error Handling - Use `GraphQLError` with extension codes - Return errors in payload for mutations - Common codes: `UNAUTHENTICATED`, `FORBIDDEN`, `BAD_USER_INPUT`, `INTERNAL_SERVER_ERROR` ``` ## Creating Agents Agents are specialized AI assistants that run automatically or on demand. ### Example: Code Review Agent `.claude/agents/code-reviewer.md`: ```markdown # Code Review Agent You are a code review agent. After code changes are made, perform a thorough review. ## Review Checklist ### TypeScript - [ ] Strict mode compliance (no `any`, proper null checks) - [ ] Proper type imports/exports - [ ] Generic types used appropriately ### Error Handling - [ ] API calls wrapped in try/catch - [ ] User-facing errors handled gracefully - [ ] Loading states implemented - [ ] Error boundaries for React components ### Testing - [ ] Tests added for new features - [ ] Edge cases covered - [ ] Mocks use factory pattern - [ ] Tests follow AAA pattern ### GraphQL - [ ] Mutations return payload with errors - [ ] Queries handle authentication - [ ] Proper error codes used ### Performance - [ ] No unnecessary re-renders - [ ] API calls properly memoized - [ ] Images optimized ## Review Process 1. Read changed files 2. Check against each category 3. Provide specific line-level feedback 4. Suggest improvements with code examples 5. Highlight what was done well Be constructive and specific. Reference exact lines and provide working alternatives. ``` ## Creating Commands Commands are custom slash commands accessible via `/command-name`. ### Example: PR Review Command `.claude/commands/pr-review.md`: ```markdown # PR Review Command **Usage:** `/pr-review [pr-number]` **Description:** Perform a comprehensive PR review with detailed feedback. ## Process 1. Fetch PR details: `gh pr view {{pr-number}} --json title,body,files` 2. Read all changed files 3. Review against project standards (see `.claude/agents/code-reviewer.md`) 4. Check for: - Breaking changes - Migration requirements - Test coverage - Documentation updates 5. Generate review summary with: - Overview of changes - Issues found (categorized by severity) - Suggestions for improvement - Approval recommendation ## Output Format ```markdown ## PR Review: {{title}} ### Summary Brief overview of what changed ### Issues Found #### 🔴 Critical - Issue with line reference and fix #### 🟡 Suggestions - Improvement ideas ### Test Coverage - Coverage percentage - Missing test cases ### Documentation - Docs that need updating ### Recommendation ✅ Approve with minor changes / ❌ Request changes ``` ``` ### Example: Ticket Integration Command `.claude/commands/ticket.md`: ```markdown # Ticket Command **Usage:** `/ticket <ticket-id>` **Description:** Read ticket, implement feature, update ticket status. ## Requirements - JIRA MCP server configured in `.mcp.json` - Git branch naming: `feature/TICKET-123-description` ## Workflow 1. Read ticket details via MCP: `jira_get_issue` 2. Analyze requirements and acceptance criteria 3. Check current branch or create new one 4. Implement changes following skills (testing-patterns, graphql-schema, etc.) 5. Run tests and validation 6. Update ticket with progress: `jira_update_issue` 7. Prompt user to create PR ## Implementation Steps - Parse acceptance criteria into tasks - For each task: - Implement code - Write tests - Verify functionality - Add ticket link to commit messages - Update ticket status to "In Review" ``` ## MCP Server Configuration MCP servers connect Claude to external tools (JIRA, GitHub, databases, etc.). ### .mcp.json Format Create `.mcp.json` in project root: ```json { "mcpServers": { "jira": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-jira"], "env": { "JIRA_HOST": "${JIRA_HOST}", "JIRA_EMAIL": "${JIRA_EMAIL}", "JIRA_API_TOKEN": "${JIRA_API_TOKEN}" } }, "github": { "type": "stdio", "command": "npx",