claude-code-showcase

Claude Code Project Configuration

Skill by 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

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:

# 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:

{
  "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:

---
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:

---
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:

# 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:

# 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:

{
  "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",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Set environment variables in .env (gitignored):

JIRA_HOST=yourcompany.atlassian.net
JIRA_EMAIL=you@company.com
JIRA_API_TOKEN=your_token_here
GITHUB_TOKEN=ghp_your_token_here
DATABASE_URL=postgresql://user:pass@localhost:5432/db

Skill Evaluation Hooks

Automatically suggest relevant skills based on user prompts.

Create Skill Evaluation Script

.claude/hooks/skill-eval.sh:

#!/bin/bash

PROMPT="$1"
SKILL_DIR=".claude/skills"

# Extract skill keywords from prompt
if echo "$PROMPT" | grep -qi "test\|spec\|jest\|mock"; then
  echo '{"feedback": "💡 Suggested skill: testing-patterns - activate with @testing-patterns"}'
  exit 0
fi

if echo "$PROMPT" | grep -qi "graphql\|query\|mutation\|resolver"; then
  echo '{"feedback": "💡 Suggested skill: graphql-schema - activate with @graphql-schema"}'
  exit 0
fi

if echo "$PROMPT" | grep -qi "component\|ui\|button\|form"; then
  echo '{"feedback": "💡 Suggested skill: core-components - activate with @core-components"}'
  exit 0
fi

Make executable:

chmod +x .claude/hooks/skill-eval.sh

Advanced: Node.js Skill Matcher

.claude/hooks/skill-eval.js:

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

const prompt = process.argv[2] || '';
const skillsDir = path.join(__dirname, '../skills');
const rulesPath = path.join(__dirname, 'skill-rules.json');

const rules = JSON.parse(fs.readFileSync(rulesPath, 'utf8'));

const matches = rules
  .filter(rule => {
    const keywordMatch = rule.keywords.some(kw => 
      prompt.toLowerCase().includes(kw.toLowerCase())
    );
    const pathMatch = rule.paths?.some(p => prompt.includes(p)) ?? false;
    return keywordMatch || pathMatch;
  })
  .map(r => r.skill);

if (matches.length > 0) {
  const suggestions = matches.map(s => `@${s}`).join(', ');
  console.log(JSON.stringify({
    feedback: `💡 Suggested skills: ${suggestions}`
  }));
}

.claude/hooks/skill-rules.json:

[
  {
    "skill": "testing-patterns",
    "keywords": ["test", "spec", "mock", "jest", "coverage"],
    "paths": [".test.", ".spec.", "/__tests__/"]
  },
  {
    "skill": "graphql-schema",
    "keywords": ["graphql", "query", "mutation", "resolver", "schema"],
    "paths": ["/api/", "/graphql/", ".graphql"]
  },
  {
    "skill": "core-components",
    "keywords": ["component", "ui", "button", "form", "input"],
    "paths": ["/components/", "/ui/"]
  }
]

GitHub Actions Integration

PR Review Automation

.github/workflows/pr-claude-code-review.yml:

name: Claude Code PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          npx @anthropic/claude-code review \
            --pr ${{ github.event.pull_request.number }} \
            --agent .claude/agents/code-reviewer.md \
            --post-comment

Scheduled Documentation Sync

.github/workflows/scheduled-claude-code-docs-sync.yml:

name: Monthly Docs Sync

on:
  schedule:
    - cron: '0 0 1 * *' # First day of month
  workflow_dispatch:

jobs:
  docs-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Sync Documentation
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx @anthropic/claude-code task \
            "Review commits from the last 30 days and update documentation to reflect any API changes, new features, or updated patterns. Focus on README.md, API docs, and CLAUDE.md." \
            --auto-commit \
            --commit-message "docs: monthly sync via Claude Code"
      
      - name: Create PR
        uses: peter-evans/create-pull-request@v5
        with:
          title: "docs: monthly documentation sync"
          body: "Automated documentation updates based on recent changes"
          branch: docs/monthly-sync

Weekly Code Quality Review

.github/workflows/scheduled-claude-code-quality.yml:

name: Weekly Code Quality

on:
  schedule:
    - cron: '0 0 * * 1' # Every Monday
  workflow_dispatch:

jobs:
  quality-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Random Directory Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          DIR=$(find src -type d | shuf -n 1)
          npx @anthropic/claude-code task \
            "Review all files in $DIR for code quality issues: TypeScript strict mode violations, missing error handling, test coverage gaps, performance issues. Fix any issues found." \
            --auto-commit \
            --commit-message "refactor: code quality improvements in $DIR"

Hook Patterns & Best Practices

Auto-Format on Save

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write {{file}}",
            "suppressOutput": true
          }
        ]
      }
    ]
  }
}

Run Tests on Test File Changes

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit.*\\.test\\.(ts|tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --findRelatedTests {{file}} --passWithNoTests",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

TypeScript Type Checking

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit.*\\.(ts|tsx)",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit --pretty false {{file}}",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Block Main Branch Edits

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Create a feature branch first\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Common Patterns

Multi-Skill Activation

@testing-patterns @graphql-schema Create a new GraphQL mutation for updating user profiles with comprehensive tests

Agent + Command Workflow

/ticket PROJ-123

This activates the ticket agent which:

Reads ticket via MCP
Implements feature using relevant skills
Writes tests
Updates ticket status

Progressive Skill Building

Start with core skills:

testing-patterns - How you write tests
code-style - Formatting and conventions
error-handling - How you handle errors

Add domain skills: 4. graphql-schema - API patterns 5. core-components - UI component patterns 6. state-management - Redux/Zustand patterns

Add workflow skills: 7. deployment - How to deploy 8. database-migrations - Schema changes

Troubleshooting

Hooks Not Running

Check hook syntax in settings.json
Verify command is in allowedCommands
Check timeout values (default: 30s)
Test command manually: .claude/hooks/script.sh "test prompt"

Skills Not Activating

Verify frontmatter format (YAML with ---)
Check description field includes trigger keywords
Use explicit activation: @skill-name
Review skill-eval hook logs

MCP Server Connection Issues

Verify environment variables are set
Test MCP server independently: npx @anthropic/mcp-jira test
Check .mcp.json syntax
Review Claude Code logs for connection errors

GitHub Actions Failing

Verify ANTHROPIC_API_KEY secret is set
Check Claude Code CLI is available: npx @anthropic/claude-code --version
Test locally first before pushing to CI
Review action logs for specific errors

Resources

Official Claude Code Documentation
MCP Server Protocol
Example Skills Repository
GitHub Actions Examples