claude-code-showcase README

The project's README from github.com/ChrisWiles/claude-code-showcase. As one markdown file: README.md.

Claude Code Project Configuration Showcase

Most software engineers are seriously sleeping on how good LLM agents are right now, especially something like Claude Code.

Once you've got Claude Code set up, you can point it at your codebase, have it learn your conventions, pull in best practices, and refine everything until it's basically operating like a super-powered teammate. The real unlock is building a solid set of reusable "skills" plus a few "agents" for the stuff you do all the time.

What This Looks Like in Practice

Custom UI Library? We have a skill that explains exactly how to use it. Same for how we write tests, how we structure GraphQL, and basically how we want everything done in our repo. So when Claude generates code, it already matches our patterns and standards out of the box.

Automated Quality Gates? We use hooks to auto-format code, run tests when test files change, type-check TypeScript, and even block edits on the main branch. Claude Code also created a bunch of ESLint automation, including custom rules and lint checks that catch issues before they hit review.

Deep Code Review? We have a code review agent that Claude runs after changes are made. It follows a detailed checklist covering TypeScript strict mode, error handling, loading states, mutation patterns, and more. When a PR goes up, we have a GitHub Action that does a full PR review automatically.

Scheduled Maintenance? We've got GitHub workflow agents that run on a schedule:

Intelligent Skill Suggestions? We built a skill evaluation system that analyzes every prompt and automatically suggests which skills Claude should activate based on keywords, file paths, and intent patterns.

A ton of maintenance and quality work is just... automated. It runs ridiculously smoothly.

JIRA/Linear Integration? We connect Claude Code to our ticket system via MCP servers. Now Claude can read the ticket, understand the requirements, implement the feature, update the ticket status, and even create new tickets if it finds bugs along the way. The /ticket command handles the entire workflow—from reading acceptance criteria to linking the PR back to the ticket.

We even use Claude Code for ticket triage. It reads the ticket, digs into the codebase, and leaves a comment with what it thinks should be done. So when an engineer picks it up, they're basically starting halfway through already.

There is so much low-hanging fruit here that it honestly blows my mind people aren't all over it.

Table of Contents

Directory Structure

your-project/
├── CLAUDE.md                      # Project memory (alternative location)
├── .mcp.json                      # MCP server configuration (JIRA, GitHub, etc.)
├── .claude/
│   ├── settings.json              # Hooks, environment, permissions
│   ├── settings.local.json        # Personal overrides (gitignored)
│   ├── settings.md                # Human-readable hook documentation
│   ├── .gitignore                 # Ignore local/personal files
│   │
│   ├── agents/                    # Custom AI agents
│   │   └── code-reviewer.md       # Proactive code review agent
│   │
│   ├── commands/                  # Slash commands (/command-name)
│   │   ├── onboard.md             # Deep task exploration
│   │   ├── pr-review.md           # PR review workflow
│   │   └── ...
│   │
│   ├── hooks/                     # Hook scripts
│   │   ├── skill-eval.sh          # Skill matching on prompt submit
│   │   ├── skill-eval.js          # Node.js skill matching engine
│   │   └── skill-rules.json       # Pattern matching configuration
│   │
│   ├── skills/                    # Domain knowledge documents
│   │   ├── README.md              # Skills overview
│   │   ├── testing-patterns/
│   │   │   └── SKILL.md
│   │   ├── graphql-schema/
│   │   │   └── SKILL.md
│   │   └── ...
│   │
│   └── rules/                     # Modular instructions (optional)
│       ├── code-style.md
│       └── security.md
│
└── .github/
    └── workflows/
        ├── pr-claude-code-review.yml           # Auto PR review
        ├── scheduled-claude-code-docs-sync.yml # Monthly docs sync
        ├── scheduled-claude-code-quality.yml   # Weekly quality review
        └── scheduled-claude-code-dependency-audit.yml

Quick Start

1. Create the .claude directory

mkdir -p .claude/{agents,commands,hooks,skills}

2. Add a CLAUDE.md file

Create CLAUDE.md in your project root with your project's key information. See CLAUDE.md for a complete example.

# Project Name

## Quick Facts
- **Stack**: React, TypeScript, Node.js
- **Test Command**: `npm run test`
- **Lint Command**: `npm run lint`

## Key Directories
- `src/components/` - React components
- `src/api/` - API layer
- `tests/` - Test files

## Code Style
- TypeScript strict mode
- Prefer interfaces over types
- No `any` - use `unknown`

3. Add settings.json with hooks

Create .claude/settings.json. See settings.json for a full example with auto-formatting, testing, and more.

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

4. Add your first skill

Create .claude/skills/testing-patterns/SKILL.md. See testing-patterns/SKILL.md for a comprehensive example.

---
name: testing-patterns
description: Jest testing patterns for this project. Use when writing tests, creating mocks, or following TDD workflow.
---

# Testing Patterns

## Test Structure
- Use `describe` blocks for grouping
- Use `it` for individual tests
- Follow AAA pattern: Arrange, Act, Assert

## Mocking
- Use factory functions: `getMockUser(overrides)`
- Mock external dependencies, not internal modules

Tip: The description field is critical—Claude uses it to decide when to apply the skill. Include keywords users would naturally mention.

Configuration Reference

CLAUDE.md - Project Memory

CLAUDE.md is Claude's persistent memory that loads automatically at session start.

Locations (in order of precedence):

  1. .claude/CLAUDE.md (project, in .claude folder)
  2. ./CLAUDE.md (project root)
  3. ~/.claude/CLAUDE.md (user-level, all projects)

What to include:

📄 Example: CLAUDE.md

settings.json - Hooks & Environment

The main configuration file for hooks, environment variables, and permissions.

Location: .claude/settings.json

📄 Example: settings.json | Human-readable docs

Hook Events

Event When It Fires Use Case
PreToolUse Before tool execution Block edits on main, validate commands
PostToolUse After tool completes Auto-format, run tests, lint
UserPromptSubmit User submits prompt Add context, suggest skills
Stop Agent finishes Decide if Claude should continue

Hook Response Format

{
  "block": true,           // Block the action (PreToolUse only)
  "message": "Reason",     // Message to show user
  "feedback": "Info",      // Non-blocking feedback
  "suppressOutput": true,  // Hide command output
  "continue": false        // Whether to continue
}

Exit Codes

MCP Servers - External Integrations

MCP (Model Context Protocol) servers let Claude Code connect to external tools like JIRA, GitHub, Slack, databases, and more. This is how you enable workflows like "read a ticket, implement it, and update the ticket status."

Location: .mcp.json (project root, committed to git for team sharing)

📄 Example: .mcp.json

How MCP Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│   MCP Server    │────▶│  External API   │
│                 │◀────│  (local bridge) │◀────│  (JIRA, GitHub) │
└─────────────────┘     └─────────────────┘     └─────────────────┘

MCP servers run locally and provide Claude with tools to interact with external services. When you configure a JIRA MCP server, Claude gets tools like jira_get_issue, jira_update_issue, jira_create_issue, etc.

.mcp.json Format

{
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-name"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Fields:

Field Required Description
type Yes Server type: stdio (local process) or http (remote)
command For stdio Executable to run (e.g., npx, python)
args No Command-line arguments
env No Environment variables (supports ${VAR} expansion)
url For http Remote server URL
headers For http HTTP headers for authentication

Example: JIRA Integration

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

What this enables:

Example workflow with /ticket command:

You: /ticket PROJ-123

Claude:
1. Fetching PROJ-123 from JIRA...
   "Add user profile avatar upload"

2. Reading acceptance criteria...
   - Upload button on profile page
   - Support JPG/PNG up to 5MB
   - Show loading state

3. Searching codebase for related files...
   Found: src/screens/Profile/ProfileScreen.tsx

4. Creating branch: cw/PROJ-123-avatar-upload

5. [Implements feature...]

6. Updating JIRA status to "In Review"
   Adding comment: "PR #456 ready for review"

7. Creating PR linked to PROJ-123...

Common MCP Server Configurations

Issue Tracking:

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

Code & DevOps:

{
  "github": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-github"],
    "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
  },
  "sentry": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-sentry"],
    "env": {
      "SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}",
      "SENTRY_ORG": "${SENTRY_ORG}"
    }
  }
}

Communication:

{
  "slack": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
      "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
    }
  }
}

Databases:

{
  "postgres": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-postgres"],
    "env": { "DATABASE_URL": "${DATABASE_URL}" }
  }
}

Environment Variables

MCP configs support variable expansion:

Set these in your shell profile or .env file (don't commit secrets!):

export JIRA_HOST="https://yourcompany.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"

Settings for MCP

In settings.json, you can auto-approve MCP servers:

{
  "enableAllProjectMcpServers": true
}

Or approve specific servers:

{
  "enabledMcpjsonServers": ["jira", "github", "slack"]
}

LSP Servers - Real-Time Code Intelligence

LSP (Language Server Protocol) gives Claude real-time understanding of your code—type information, errors, completions, and navigation. Instead of just reading text, Claude can "see" your code the way your IDE does.

Why this matters: When you edit TypeScript, Claude immediately knows if you introduced a type error. When you reference a function, Claude can jump to its definition. This dramatically improves code generation quality.

Enabling LSP

LSP support is enabled through plugins in settings.json:

{
  "enabledPlugins": {
    "typescript-lsp@claude-plugins-official": true,
    "pyright-lsp@claude-plugins-official": true
  }
}

What Claude Gets from LSP

Feature Description
Diagnostics Real-time errors and warnings after every edit
Type Information Hover info, function signatures, type definitions
Code Navigation Go to definition, find references
Completions Context-aware symbol suggestions

Available LSP Plugins

Plugin Language Install Binary First
typescript-lsp TypeScript/JavaScript npm install -g typescript-language-server typescript
pyright-lsp Python pip install pyright
rust-lsp Rust rustup component add rust-analyzer

Custom LSP Configuration

For advanced setups, create .lsp.json:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact"
    },
    "initializationOptions": {
      "preferences": {
        "quotePreference": "single"
      }
    }
  }
}

Troubleshooting

If LSP isn't working:

  1. Check binary is installed:

    which typescript-language-server  # Should return a path

  2. Enable debug logging:

    claude --enable-lsp-logging

  3. Check plugin status:

    claude /plugin  # View Errors tab

Skill Evaluation Hooks

One of our most powerful automations is the skill evaluation system. It runs on every prompt submission and intelligently suggests which skills Claude should activate.

📄 Files: skill-eval.sh | skill-eval.js | skill-rules.json

How It Works

When you submit a prompt, the UserPromptSubmit hook triggers our skill evaluation engine:

  1. Prompt Analysis - The engine analyzes your prompt for:

    • Keywords: Simple word matching (test, form, graphql, bug)
    • Patterns: Regex matching (\btest(?:s|ing)?\b, \.stories\.)
    • File Paths: Extracts mentioned files (src/components/Button.tsx)
    • Intent: Detects what you're trying to do (create.*test, fix.*bug)

  2. Directory Mapping - File paths are mapped to relevant skills:

    {
  "src/components/core": "core-components",
  "src/graphql": "graphql-schema",
  ".github/workflows": "github-actions",
  "src/hooks": "react-ui-patterns"
}

  3. Confidence Scoring - Each trigger type has a point value:

    {
  "keyword": 2,
  "keywordPattern": 3,
  "pathPattern": 4,
  "directoryMatch": 5,
  "intentPattern": 4
}

  4. Skill Suggestion - Skills exceeding the confidence threshold are suggested with reasons:

    SKILL ACTIVATION REQUIRED

Detected file paths: src/components/UserForm.tsx

Matched skills (ranked by relevance):
1. formik-patterns (HIGH confidence)
   Matched: keyword "form", path "src/components/UserForm.tsx"
2. react-ui-patterns (MEDIUM confidence)
   Matched: directory mapping, keyword "component"

Configuration

Skills are defined in skill-rules.json:

{
  "testing-patterns": {
    "description": "Jest testing patterns and TDD workflow",
    "priority": 9,
    "triggers": {
      "keywords": ["test", "jest", "spec", "tdd", "mock"],
      "keywordPatterns": ["\\btest(?:s|ing)?\\b", "\\bspec\\b"],
      "pathPatterns": ["**/*.test.ts", "**/*.test.tsx"],
      "intentPatterns": [
        "(?:write|add|create|fix).*(?:test|spec)",
        "(?:test|spec).*(?:for|of|the)"
      ]
    },
    "excludePatterns": ["e2e", "maestro", "end-to-end"]
  }
}

Adding to Your Project

  1. Copy the hooks to your project:

    cp -r .claude/hooks/ your-project/.claude/hooks/

  2. Add the hook to your settings.json:

    {
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/skill-eval.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

  3. Customize skill-rules.json with your project's skills and triggers.

Skills - Domain Kn

claude-code-showcase (ChrisWiles/claude-code-showcase)

Searching Database…

6.1K ·GitHub
Claude-code-showcase
这是什么？这是一个参考代码仓库，展示了完整的 Claude Code 项目配置，包括钩子、技能、代理、斜杠命令、MCP 服务器、LSP 集成以及 GitHub Actions 工作流，你可以直接复制到自己的项目中。
这是一个我需要安装的插件，还是只是需要复制的示例文件？它不是可以安装的软件包，而是一套配置文件模板（CLAUDE.md、settings.json、技能、代理、工作流），用于复制到你自己的 .claude 目录中并加以修改。
我该如何在自己的项目中设置这些？创建一个 .claude 目录，添加一个写有项目信息的 CLAUDE.md 文件，再添加包含钩子的 settings.json，然后按照这里的示例，在 .claude/skills/ /SKILL.md 下添加你的第一个技能。
使用 LSP 示例除了 Claude Code 之外还需要别的东西吗？需要。每个 LSP 插件都需要单独安装对应的语言服务器，例如 TypeScript 需要 typescript-language-server，Python 需要 pyright，Rust 需要 rust-analyzer。
我能直接把这些文件丢进仓库，就让它正常运行吗？不太行。钩子、skill-rules.json、MCP 服务器和 GitHub Actions 都需要根据你自己的代码库、工单系统和凭据进行定制，否则无法发挥实际作用。
什么是技能评估系统？这是一个 UserPromptSubmit 钩子，它会分析每条提示词中的关键词、正则表达式模式、文件路径和意图，然后根据 skill-rules.json 中定义的置信度评分，建议激活哪些 Claude Code 技能。
JIRA 集成是如何工作的？一个 MCP 服务器将 Claude 与 JIRA 连接起来，使其能够读取工单详情和验收标准、更新状态、添加评论以及创建新工单，所有操作都通过随附的 /ticket 斜杠命令完成。
附带的 GitHub Actions 工作流有什么作用？其中一个会自动进行 PR 代码审查，另外还有定时工作流，负责每月同步文档、每周修复代码质量问题，以及每两周进行一次依赖审计并验证测试。
为什么这里要用 LSP 服务器，而不是让 Claude 直接读取文本？LSP 插件让 Claude 像 IDE 一样获得实时诊断、类型信息和跳转到定义的能力，因此它能立刻知道某次编辑是否引入了类型错误，而不必仅凭纯文本去猜。
What are similar projects?agentic-playwright, pstack, Claude-Code-Game-Studios, pstack-claude, open-swe, everything-claude-code, claude-code-infrastructure-showcase, claude-plugins-official
Which topics is it in?linting, jira, language-server-protocol, claude-code-skills, eslint, hooks, template, code-review, best-practices, github-actions, workflow-automation, ci
Creator
ChrisWiles
Size
0.1 MB
Stars
6.1K
Updated
CommitJan 06
Age
9mo
Commits · 90 Days