Ultimate Guide to Claude Code Setup: Hooks, Skills & Actions

Claude Code turns an ordinary codebase into a team member that can read, write, refactor, and even manage tickets. Whether you’re a solo developer or part of a large team, this tutorial gives you a full, hands‑on configuration that covers: * Project memory via CLAUDE.md * Runtime hooks, environment variables, and command restrictions * Reusable “skills” for patterns, tests, and architecture * MCP servers for JIRA, GitHub, Slack … * LSP integration for real‑time diagnostics * Custom agents and slash commands * GitHub Actions for PR reviews, quality checks, and scheduled jobs

1. Why Claude Code?

Traditional LLM assistants often read code as plain text. Claude Code changes that by:

With these pieces, Claude becomes a trusted teammate rather than a simple code‑generation tool.

2. Project Layout Overview

your‑project/
├── .claude/
│   ├── agents/          # Custom AI agents
│   ├── commands/        # Slash commands
│   ├── hooks/           # Hook scripts & rules
│   ├── skills/          # Domain‑specific knowledge
│   ├── settings.json    # Global hooks & env vars
│   └── settings.md      # Human‑readable docs
├── .mcp.json            # MCP server config (JIRA, GitHub, etc.)
├── .github/workflows/   # GitHub Actions
├── CLAUDE.md            # Project memory – top‑level
└── README.md

Tip: Store any user‑specific overrides in a .claude/settings.local.json or a personal CLAUDE.local.md – these files should be ignored by Git.

3. Quick Start: Create the Boilerplate

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

# Basic CLAUDE.md – edit to suit your stack
cat <<'EOF' > CLAUDE.md
# My Awesome Project

## Stack
- React
- TypeScript
- Node.js

## Key Directories
- src/components/  # UI
- src/api/         # API layer
- tests/           # Jest tests

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

# Basic settings.json with a simple PreToolUse hook
cat <<'EOF' > .claude/settings.json
{
  "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
          }
        ]
      }
    ]
  }
}
EOF

Run git add -A && git commit -m "Initial Claude Code configuration" to save the scaffolding.

4. Project Memory: CLAUDE.md

CLAUDE.md is Claude’s persistent memory that loads on every session. Keep it concise but complete:

• Stack & architecture – Quick stack overview.
• Key commands – npm run test, npm run lint, npm run build.
• Code style guidelines – Any linting rules, type‑strictness.
• Critical directories – Where are components, utilities, or tests located.
• Any special constraints – e.g., no editing on main branch.

Claude reads this file first, so place your most important information at the top.

5. Hooks & Environment: .claude/settings.json

Hooks allow you to intercept tool calls or user prompts. A typical config will contain:

Example: Block edits on main

"PreToolUse": [
  {"matcher": "Edit|Write", "hooks": ["if [ \"$(git branch --show-current)\" != \"main\" ]; then echo 'Allowed'; else echo 'Blocked'; fi"]}
]

You can also add environment variables for secrets (JIRA API tokens, etc.). The file is committed because secrets are referenced via ${VAR} placeholders that load at runtime.

6. Skills: Reusable Domain Knowledge

Skills are Markdown files that teach Claude how to write code in your style. Every skill lives under .claude/skills/{skill-name}/SKILL.md.

Skill Frontmatter Example

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

The description field is crucial – Claude uses it to decide when the skill should activate. Include natural language keywords (e.g., test, jest, mock).

Example Skill Content

# Testing Patterns

## Arrange-Act-Assert

```ts
// Arrange
const mockUser = getMockUser();

// Act
const result = login(mockUser);

// Assert
expect(result).toBeTruthy();

Mocking

Prefer factory functions over global mocks to keep tests deterministic.

Adding a New Skill

1. Create .claude/skills/{skill-name}/SKILL.md.
2. Write a succinct description.
3. Implement code examples.
4. Update skill-rules.json if needed to map triggers.
5. Add the skill directory to Git and commit.

7. Skill‑Evaluation Hooks

When a user submits a prompt, the UserPromptSubmit hook runs a small engine that looks for:

• Keywords – e.g., write test.
• Path patterns – e.g., src/components/*.
• Intent patterns – regular expressions that capture common requests.
• Directory mapping – links file paths to skill names.

The hook outputs JSON specifying which skills to activate, e.g.,

{"activate": ["testing-patterns", "react-ui-patterns"]}

Tip: Keep skill-rules.json lean – add new rules as new patterns emerge.

8. MCP Servers: Connect to External Tools

MCP (Model Context Protocol) servers give Claude direct access to services like JIRA, GitHub, Slack, Sentry, or Postgres. Configure them in .mcp.json.

Example: JIRA & GitHub

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

Store the real tokens in environment variables or a .env file that is not committed.

The /ticket Command

A slash command /ticket can read a JIRA issue, generate a branch, implement the requested feature, and close the ticket automatically. Detailed instructions are available in .claude/commands/ticket.md.

9. LSP Support

Add Language Server Protocol plugins to give Claude real‑time diagnostics:

// .claude/settings.json
"enabledPlugins": {
  "typescript-lsp@claude-plugins-official": true,
  "pyright-lsp@claude-plugins-official": true
}

Make sure the LSP binaries are installed (e.g., npm i -g typescript-language-server). LSP gives Claude:

• Diagnostics – type errors on edit.
• Intellisense – function signatures and type info.
• Navigation – jump to definitions.
• Completions – context‑aware suggestions.

10. Agents & Commands

Agents

Agents are focused assistants. A code-reviewer agent might automatically run a checklist and comment on pull requests.

---
name: code-reviewer
description: Reviews TypeScript code for style, safety, and tests.
model: opus
---

Commands

Slash commands execute custom workflows. For example, /pr-review expands a PR, reviews changes, and leaves a comment.

---
description: Review current PR using standard checklist.
allowed-tools: Bash(git:*), Read, Grep
---

Create the markdown file under .claude/commands/ and reference it in your GitHub Actions.

11. GitHub Actions Automation

Automate quality gates, docs sync, and dependency audits with workflows located in .github/workflows/. Typical examples:

• Auto PR Review – triggers on PR events and runs Claude code-reviewer.
• Scheduled Docs Sync – runs monthly to ensure docs reflect latest code.
• Weekly Code Quality – random directory scans with auto‑fix.
• Bi‑weekly Dependency Audit – safe updates with test verification.

A minimal PR review workflow:

name: PR - Claude Review
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-opus-4-5-20251101
          prompt: |
            Review this PR using .claude/agents/code-reviewer.md standards.
            Run `git diff origin/main...HEAD` to see changes.

Add ANTHROPIC_API_KEY to Repository Secrets for API access.

12. Best Practices

1. Start with CLAUDE.md – keep it brief but complete.
2. Incrementally build skills – focus on high‑impact patterns.
3. Use hooks for repetitive tasks – avoid manual linting or test failures.
4. Create agents for complex workflows – e.g., bug triage, pull‑request summarizers.
5. Automate with GitHub Actions – schedule quality sweeps and docs syncs.
6. Version your config – commit all files except personal overrides.
7. Secure sensitive data – use environment variables and do not commit secrets.
8. Measure cost – run a cost estimate table to keep usage predictable.

13. Wrap‑Up

With this configuration, your repository is now:

• Self‑aware – Claude understands stack, style, and conventions.
• Automated – code formatting, testing, and quality gates run automatically.
• Connected – tickets, PRs, and chats tie directly into Claude’s workflow.
• Extensible – new skills, agents, and commands can be added in minutes.

Start by cloning the repository, customizing the snippets to your own stack, and letting Claude become the teammate you never knew you needed.

Happy coding!