How to Set Up Claude Code for a Project with Skills, Agents, Hooks, and a Secure GitHub Repository

How to Set Up Claude Code for a Project with Skills, Agents, Hooks, and a Secure GitHub Repository

AI coding tools work best when they understand the project around the code. A fresh Claude Code session can answer questions and edit files, but it does not automatically know your architecture decisions, coding standards, security expectations, testing rules, pull request format, or operational constraints. That context needs to live somewhere predictable.

This guide walks through a full Claude Code project setup using a reusable repository owned by desertfox33:

Reference repository: https://github.com/desertfox33/claude-code-project-template

The goal is not just to create folders. The goal is to make Claude Code behave consistently across real project work: reviewing code, writing tests, preparing pull requests, checking security concerns, and following project-specific rules.

Before using this setup in a production environment, verify current Claude Code behavior against the latest official documentation. Tooling, configuration names, and feature behavior can change.

What We Are Building

The repository uses this structure:

claude-code-project-template/
├── CLAUDE.md
├── CLAUDE.local.md.example
├── AGENTS.md
├── .mcp.example.json
├── .gitignore
├── SECURITY.md
├── CONTRIBUTING.md
├── .github/
│   ├── CODEOWNERS
│   ├── dependabot.yml
│   └── pull_request_template.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json.example
│   ├── rules/
│   │   ├── code-style.md
│   │   ├── api-conventions.md
│   │   ├── testing-standard.md
│   │   └── pr.md
│   ├── commands/
│   │   ├── review.md
│   │   ├── deploy.md
│   │   ├── scaffold.md
│   │   ├── test.md
│   │   └── pr.md
│   ├── skills/
│   │   ├── code-review/
│   │   │   ├── SKILL.md
│   │   │   └── review-checklist.md
│   │   ├── testing-patterns/
│   │   │   ├── SKILL.md
│   │   │   └── test-strategy.md
│   │   ├── pr-description/
│   │   │   ├── SKILL.md
│   │   │   └── template.md
│   │   └── security-review/
│   │       └── SKILL.md
│   ├── agents/
│   │   ├── security-reviewer.md
│   │   ├── test-writer.md
│   │   └── research.md
│   ├── hooks/
│   │   ├── validate-code.sh
│   │   ├── post-edit-format.sh
│   │   ├── block-dangerous-bash.sh
│   │   └── block-sensitive-writes.sh
│   ├── memory/
│   │   ├── project-context.md
│   │   ├── decisions.md
│   │   └── progress.md
│   └── workflows/
│       ├── feature-build.md
│       ├── bug-fix.md
│       └── code-review.md
├── scripts/
│   └── check-repo-safety.sh
└── blog/
    └── devto-claude-code-project-setup.md

This layout separates long-lived context from task-specific context. That makes the setup easier to maintain and reduces the chance that Claude will load irrelevant instructions for every task.

The Mental Model

Think of the project as several layers.

• CLAUDE.md is the project briefing. It contains information Claude should know in every session: project purpose, tech stack, architecture rules, coding standards, security expectations, and how to use the rest of the repository.
• CLAUDE.local.md is for personal overrides. It should stay local and should not be committed. Use it for machine-specific notes, local paths, personal preferences, and temporary experiments.
• .claude/rules/ contains focused rule files. Use rules when the instruction applies across multiple tasks but does not need to be loaded into the main project briefing every time.
• .claude/skills/ contains reusable task expertise. Use skills when Claude should follow a specific process for a repeatable task, such as reviewing code, writing tests, creating a pull request description, or performing a security review.
• .claude/commands/ contains project-specific slash commands. Use commands when you want a short, repeatable entry point such as /review, /test, or /pr.
• .claude/agents/ contains specialized subagent definitions. Use agents when a task benefits from an isolated role, such as security review, test writing, or research.
• .claude/hooks/ contains scripts that enforce behavior around tool use or file changes. Treat hooks as code because they can execute commands.
• .claude/memory/ contains persistent project context, decisions, and progress notes.
• .claude/workflows/ contains repeatable task blueprints for larger work such as feature builds, bug fixes, and review cycles.
• .mcp.example.json is the committed example for Model Context Protocol configuration. The real .mcp.json should normally stay local-only and be ignored by Git because it can contain local paths, commands, environment references, or credentials. MCP can connect Claude to external tools and data sources, so treat it as security-sensitive configuration.

Step 1: Start with CLAUDE.md

Put CLAUDE.md at the root of the repository. Use it for context Claude should always have. Do not turn it into a dumping ground.

A good CLAUDE.md should answer these questions:

• What does this project do?
• What tech stack does it use?
• What standards should code follow?
• What files should never be edited without approval?
• Which skills, agents, commands, hooks, and workflows exist?
• What security and testing expectations apply?

Example content:

# Project Instructions for Claude Code

This repository is maintained by desertfox33.

## Project Purpose

This project is a reusable Claude Code template for structured AI-assisted development.

## Working Rules

- Prefer small, reviewable changes.
- Explain security impact when changing hooks, MCP config, agents, or skills.
- Never commit secrets, tokens, private keys, or local override files.
- Follow project rules in `.claude/rules/`.
- Use skills when the task matches a known repeatable process.

## Skills

- Use `code-review` for maintainability, correctness, reliability, and security review.
- Use `testing-patterns` when writing or improving tests.
- Use `pr-description` when preparing pull request summaries.
- Use `security-review` when reviewing sensitive changes, auth, data handling, hooks, MCP, or automation.

Where to use it

Use CLAUDE.md in every Claude Code project. It is the project's operating guide.

What not to put in it

Do not put private secrets, local filesystem paths, temporary notes, or large rule documents in CLAUDE.md. Put local-only data in CLAUDE.local.md and detailed rules in .claude/rules/.

Step 2: Add Local Overrides with CLAUDE.local.md

Create an example file: CLAUDE.local.md.example

Developers can copy it locally:

cp CLAUDE.local.md.example CLAUDE.local.md

Then add the real file to .gitignore:

CLAUDE.local.md

Where to use it

Use CLAUDE.local.md for personal preferences and local context:

# Local Claude Notes

- My local test command is `npm test`.
- My local project path is `/Users/example/projects/claude-code-project-template`.
- Ask before running long-running commands.

Why it matters

Local overrides are useful, but they can leak private details. Keeping them out of Git protects personal paths, internal environment notes, and temporary instructions.

Step 3: Add Modular Rules

Rules live here: .claude/rules/

This repository includes:

• .claude/rules/code-style.md
• .claude/rules/api-conventions.md
• .claude/rules/testing-standard.md
• .claude/rules/pr.md

Which rules to use

• Use code-style.md when Claude is editing application code. It should define naming, structure, readability expectations, error handling, and maintainability standards.
• Use api-conventions.md when Claude is working on APIs. It should define route naming, validation expectations, error responses, authentication assumptions, and compatibility requirements.
• Use testing-standard.md when Claude is writing or reviewing tests. It should define unit test style, integration test expectations, coverage priorities, fixtures, mocking rules, and failure cases.
• Use pr.md when Claude is preparing pull requests. It should define PR title format, description structure, testing evidence, security impact, and rollback considerations.

Example: testing-standard.md

# Testing Standard

When writing tests:

- Cover success, failure, and edge cases.
- Prefer meaningful test names over clever assertions.
- Keep unit tests deterministic.
- Avoid network calls in unit tests.
- Include regression tests for bug fixes.
- Document any intentionally untested behavior.

Practical guidance

Keep each rule file focused. If a rule is only relevant to code review, keep it in the code review skill. If it applies to all code changes, put it in .claude/rules/.

Step 4: Add Skills

Skills live here: .claude/skills/<skill-name>/SKILL.md

Each skill should be one job. Do not create a single oversized skill that tries to do everything.

This repository includes four skills.

Skill 1: code-review

Location: .claude/skills/code-review/SKILL.md and .claude/skills/code-review/review-checklist.md

When to use it: Use code-review when Claude should review a branch, file, folder, or pull request for:

• Correctness
• Maintainability
• Reliability
• Security concerns
• Test coverage
• Error handling
• Breaking changes
• Operational risk

How to use it: Ask Claude: "Use the code-review skill to review the changes in this branch." Or: "Use the code-review skill to review src/auth for correctness, security, and test coverage."

What the skill should do: The skill should instruct Claude to:

1. Identify changed files.
2. Understand the intended behavior.
3. Review for correctness and edge cases.
4. Check for security-sensitive changes.
5. Check testing impact.
6. Categorize findings by severity.
7. Avoid nitpicks unless they affect maintainability or risk.

Example output format:

## Summary
Short explanation of what was reviewed.

## High-Risk Findings
- Finding, impact, evidence, recommendation.

## Medium-Risk Findings
- Finding, impact, evidence, recommendation.

## Testing Gaps
- Missing tests or weak coverage.

## Safe to Merge?
Decision and reason.

Where it helps most: Use this skill before merging code, before opening a pull request, or after a large AI-assisted edit.

Skill 2: testing-patterns

Location: .claude/skills/testing-patterns/SKILL.md and .claude/skills/testing-patterns/test-strategy.md

When to use it: Use testing-patterns when Claude should:

• Write unit tests
• Improve existing tests
• Add regression tests
• Identify missing test cases
• Design test strategy for new features
• Convert vague acceptance criteria into test cases

How to use it: "Use the testing-patterns skill to write tests for the new validation logic." Or: "Use the testing-patterns skill to identify missing tests for this bug fix."

What the skill should do: The skill should guide Claude to produce tests that are:

• Deterministic
• Focused
• Maintainable
• Clear about setup, action, and assertion
• Sensitive to edge cases and failure modes

Where it helps most: Use it after feature implementation, during bug fixes, or before opening a pull request. A practical pattern is: Implement feature → use testing-patterns → use code-review → prepare PR.

Skill 3: pr-description

Location: .claude/skills/pr-description/SKILL.md and .claude/skills/pr-description/template.md

When to use it: Use pr-description when Claude should prepare a clear pull request summary. It should include:

• What changed
• Why it changed
• How it was tested
• Security impact
• Deployment or rollback considerations
• Screenshots or logs when relevant
• Follow-up work

How to use it: "Use the pr-description skill to create a PR summary for this branch." Or: "Use the pr-description skill and include testing evidence from the latest test run."

Where it helps most: Use it right before opening a pull request. It is especially helpful when several small commits need to be explained as one coherent change.

Skill 4: security-review

Location: .claude/skills/security-review/SKILL.md

When to use it: Use security-review when a change touches:

• Authentication
• Authorization
• Session handling
• Input validation
• Secrets
• Logging
• Data access
• API endpoints
• File upload or download
• Dependencies
• CI/CD
• Hooks
• MCP configuration
• GitHub Actions
• Claude Code automation

How to use it: "Use the security-review skill to review this change for public repository safety." Or: "Use the security-review skill to inspect .claude/hooks and .mcp.json before I push this repository public."

What the skill should check: The skill should ask:

• What asset is being protected?
• What could an attacker influence?
• Could this expose secrets or private data?
• Could a hook execute unsafe commands?
• Could MCP connect to an unexpected external system?
• Could public contributors abuse automation?
• Are logs safe?
• Are permissions too broad?
• Is there a safer design?

Where it helps most: Use this skill before publishing the repo, before merging outside contributions, and before enabling automation.

Step 5: Add Project Slash Commands

Commands live here: .claude/commands/

This repository includes:

• .claude/commands/review.md
• .claude/commands/deploy.md
• .claude/commands/scaffold.md
• .claude/commands/test.md
• .claude/commands/pr.md

When to use commands instead of skills

Use a command when you want a short trigger for a repeatable workflow. Use a skill when you want reusable expertise that Claude can apply to a task.

For example:

• /review src/auth can tell Claude to run a review workflow and apply the code-review skill.
• /test src/services can tell Claude to apply the testing-patterns skill.
• /pr can tell Claude to apply the pr-description skill.

Recommended command behavior

Commands should:

• Accept arguments
• State what they will inspect
• Ask before risky actions
• Reference the relevant skill or rules
• Produce consistent output

Step 6: Add Agents

Agents live here: .claude/agents/

This repository includes:

• .claude/agents/security-reviewer.md
• .claude/agents/test-writer.md
• .claude/agents/research.md

When to use agents

Use an agent when the task benefits from a specialized role or isolated context.

• Use security-reviewer.md for security-sensitive work.
• Use test-writer.md for test design and test implementation.
• Use research.md for documentation review, unknown behavior, or technology validation.

Example prompt

"Use the security reviewer agent to inspect this pull request for risks before merge."

Practical warning

Agents are useful, but they should not become a way to avoid human review. Treat agent findings as recommendations. You still own the decision to merge, deploy, or publish.

Step 7: Add Hooks Carefully

Hooks