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

.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

.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

.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 live here:

.claude/hooks/

This repository includes:

.claude/hooks/validate-code.sh

.claude/hooks/post-edit-format.sh

.claude/hooks/block-dangerous-bash.sh

.claude/hooks/block-sensitive-writes.sh

block-dangerous-bash.sh is intended to stop obvious destructive shell commands before they run.

block-sensitive-writes.sh is intended to block edits to local-only and sensitive files such as .env, .mcp.json, credentials, private keys, and secret directories.

Both hooks must parse the Claude hook JSON payload correctly. If the hook reads the wrong input stream, it can appear to work while silently failing to inspect the requested command or file path. That is a release-blocking bug for a public template.

When to use hooks

Use hooks only when you need deterministic enforcement.

Good use cases:

• Block edits to sensitive files


• Run a formatter after edits


• Validate that certain files do not contain secrets


• Prevent accidental changes to protected paths

Poor use cases:

• Large deployment scripts


• Destructive commands


• Network calls without approval


• Commands that hide output


• Anything that changes production

Public repository risk

Hooks deserve special review because they can execute commands. In a public repository, a malicious pull request could try to modify a hook to run unsafe behavior.

That is why this repository includes:

.github/CODEOWNERS

.github/pull_request_template.md

SECURITY.md

CONTRIBUTING.md

These files remind maintainers to review sensitive areas carefully.

Step 8: Add Memory

Memory files live here:

.claude/memory/

This repository includes:

.claude/memory/project-context.md

.claude/memory/decisions.md

.claude/memory/progress.md

What belongs in memory

Use memory for persistent project knowledge:

• Important architecture decisions


• Known trade-offs


• Current progress


• Project constraints


• Major risks


• Future work

What does not belong in memory

Do not store secrets, credentials, customer data, private incident details, or anything you would not want in a public repository.

Step 9: Add Workflows

Workflows live here:

.claude/workflows/

This repository includes:

.claude/workflows/feature-build.md

.claude/workflows/bug-fix.md

.claude/workflows/code-review.md

When to use workflows

Use workflows when the work has multiple steps.

Example feature workflow:

Clarify requirements

Inspect existing code

Design small implementation plan

Implement in reviewable chunks

Write or update tests

Run validation

Review security impact

Prepare PR summary

How workflows relate to skills

Workflows can call skills at the right point.

For example:

feature-build workflow

  ├── implementation

  ├── testing-patterns skill

  ├── code-review skill

  └── pr-description skill

That keeps the project process consistent.

Step 10: Configure MCP Carefully

The committed repository should include:

.mcp.example.json

The real local file should be:

.mcp.json

For a public template repository, do not commit .mcp.json by default. Add it to .gitignore and treat it like local configuration.

MCP can connect Claude to external systems. That can be useful, but it also increases risk because an MCP server may read data, call tools, or interact with local or remote services.

Use .mcp.example.json to document the expected shape of the configuration without exposing real values.

Safe MCP pattern

Use this pattern:

Commit:     .mcp.example.json

Ignore:     .mcp.json

Review:     every MCP server, command, scope, and environment variable

Approve:    any MCP server that can write, delete, or access private data

What to review before enabling MCP

Ask:

• What external service does this connect to?


• What permissions does it have?


• Does it read private data?


• Can it write or delete data?


• Where are tokens stored?


• Is the server trusted?


• Is access limited to the minimum required scope?


• Could a public contributor modify MCP settings to access unexpected tools?

For public repositories, keep MCP configuration minimal, example-only, and documented.

Step 11: Push the Repository to GitHub as desertfox33

The target repository is:

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

From iPad, use Codespaces first

If you have not configured SSH or GPG yet, use GitHub Codespaces with HTTPS authentication.

Create the repository on GitHub:

1. Sign in as desertfox33.


2. Create a new repository.


3. Name it claude-code-project-template.


4. Set it to Public.


5. Do not initialize it with README, .gitignore, or license if you are uploading this template.

Then upload the ZIP into Codespaces and run:

unzip claude-code-project-template-desertfox33.zip

cd claude-code-project-template

rm -rf .git

git init

git branch -M main

git config user.name "desertfox33"

git config user.email "YOUR_VERIFIED_GITHUB_EMAIL"

git add .

git commit -m "Initial commit: Claude Code project template"

git remote add origin https://github.com/desertfox33/claude-code-project-template.git

git push -u origin main

Because SSH is not configured yet, Git may ask for a username and password.

Use:

Username: desertfox33

Password: your fine-grained personal access token

Do not use your GitHub account password.

Step 12: Secure the Public Repository

Public does not mean uncontrolled. People can view and fork the repository, but they cannot push directly unless you grant access.

The main risks are:

• Secrets accidentally committed to the repository


• Malicious pull requests


• Unsafe hooks


• Over-permissive GitHub Actions


• Unreviewed MCP configuration


• Dependency issues


• Accidental direct pushes to main
  

Enable account protection

For desertfox33, enable two-factor authentication.

Enable repository security features

In GitHub:

Repository → Settings → Code security and analysis

Enable what is available:

• Dependency graph


• Dependabot alerts


• Dependabot security updates


• Secret scanning


• Secret scanning push protection

Protect main

In GitHub:

Repository → Settings → Rules → Rulesets

Create:

Ruleset name: Protect main

Target branch: main

Enforcement: Active

Recommended rules:

• Require a pull request before merging


• Require at least one approval


• Dismiss stale approvals when new commits are pushed


• Require conversation resolution before merging


• Block force pushes


• Restrict branch deletion


• Require linear history


• Require status checks after you add workflows


• Require signed commits after you configure commit signing

Keep Actions conservative

In GitHub:

Repository → Settings → Actions → General

Recommended settings:

• Use read-only workflow permissions by default


• Require approval for workflows from outside contributors


• Do not expose secrets to pull requests from forks


• Review all workflow changes before merging

Step 13: Run the Repository Safety Check

Before publishing the repository, run the local safety scanner:

./scripts/check-repo-safety.sh

The safety check should fail closed. That means it must exit with a non-zero status when it finds release-blocking problems such as:

• committed .env files


• committed .mcp.json
  


• private keys


• credential files


• archive files that may contain sensitive content


• obvious token patterns


• dangerous shell patterns in automation

A scanner that only prints warnings but exits successfully is not enough for CI. If the script detects a blocking issue, CI should fail.

Recommended GitHub Actions pattern:

name: Repository Safety Check



on:

  pull_request:

  push:

    branches: [main]



permissions:

  contents: read



jobs:

  safety:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - name: Run repository safety check

        run: ./scripts/check-repo-safety.sh

This check does not replace dedicated secret scanning tools, but it gives maintainers a simple deterministic gate for public-template hygiene.

Step 14: Add SSH and Commit Signing Later

You do not need SSH or GPG to perform the first push. HTTPS with a fine-grained token is enough.

Later, from a trusted terminal:

ssh-keygen -t ed25519 -C "YOUR_VERIFIED_GITHUB_EMAIL"

cat ~/.ssh/id_ed25519.pub

Upload only the public key to GitHub.

For verified commits, configure either SSH commit signing or GPG commit signing. After it works, enable signed commits in your repository ruleset.

Practical Checklist

Before making the repository public, check:

• [ ] Repository URL uses desertfox33.


• [ ] No files reference someone else’s template repository.


• [ ] .gitignore blocks local Claude overrides, .mcp.json, and secret files.


• [ ] No .env file is committed.


• [ ] No private key is committed.


• [ ] No real token is committed.


• [ ] .mcp.json is not committed; only .mcp.example.json is committed.


• [ ] ./scripts/check-repo-safety.sh passes locally and fails closed in CI.


• [ ] Hook scripts correctly parse the Claude hook JSON payload.


• [ ] Dangerous shell commands are blocked by block-dangerous-bash.sh.


• [ ] Sensitive local files are blocked by block-sensitive-writes.sh.


• [ ] SECURITY.md exists.


• [ ] CONTRIBUTING.md exists.


• [ ] .github/CODEOWNERS assigns sensitive paths to @desertfox33.


• [ ] Pull request template includes a safety checklist.


• [ ] GitHub security features are enabled.


• [ ] main is protected.


• [ ] Public contributors must use pull requests.

Common Mistakes

The most common mistake is treating Claude configuration files as simple documentation. They are more important than that. Skills, hooks, agents, commands, and MCP files can influence how work is performed.

Review them like code.

Another common mistake is committing .mcp.json to a public template. Keep the real file local and commit only .mcp.example.json.

A third mistake is writing hooks that do not correctly read the hook payload. A hook can look safe but fail open if it parses the wrong input stream.

A fourth mistake is using a safety scanner that prints warnings but still exits successfully. Public-release checks should fail closed when they find blocking issues.

A fifth mistake is making a repository public before checking for secrets. Run a local scan, review the file tree, and keep real local files out of Git.

A sixth mistake is giving contributors direct write access. For a public project, forks and pull requests are safer.

Practical Takeaway

A good Claude Code setup gives Claude the right context at the right time.

Use CLAUDE.md for project-wide instructions. Use rules for standards. Use skills for repeatable expertise. Use commands for shortcuts. Use agents for focused roles. Use hooks only where deterministic enforcement is worth the risk. Use memory and workflows to keep long-running work organized. Use a fail-closed repository safety check before publishing or merging.

For a public GitHub repository, secure the publishing process before accepting contributions. The repository can be public and useful without allowing unknown users to change it directly.