Skip to main content

Claude Code Customization

Claude Code has its own file-based customization system, parallel to Copilot's. This page covers the files you commit to a repo so the whole team gets the same behavior: CLAUDE.md, skills, subagents, hooks, permission settings, and MCP configuration.

note

Claude Code ships updates frequently. Treat the field names and examples here as a starting point and check the Claude Code docs for the current details.

Overview — Which File Does What?​

FileLocationActivationPrimary Use
CLAUDE.mdRepo root (and subfolders)Loaded at session start; subfolder files when Claude works thereProject context, commands, conventions
SKILL.md.claude/skills/<skill-name>/Claude loads it when the description matches the task, or you run /skill-namePackaged workflows with supporting files
Subagents.claude/agents/*.mdClaude delegates to them, or you ask for one by nameSpecialized workers with their own context, tools, and model
Settings.claude/settings.jsonAlwaysPermissions, hooks, environment variables
MCP config.mcp.json (repo root)Always (after you approve the servers)External tools and data sources

Personal versions of most of these live in ~/.claude/ and apply to all your projects. Personal overrides for one repo go in .claude/settings.local.json. When Claude Code creates that file itself it adds it to your global git excludes; if you create it by hand, add it to .gitignore yourself.

CLAUDE.md​

The main project context file — stack, commands, conventions. It's covered in Prompt Engineering → Claude Code. Two points matter for teams:

  • Keep it short. It is sent with every request. Put long, task-specific procedures in a skill instead.
  • Share with other tools through AGENTS.md. If the repo already has an AGENTS.md, add @AGENTS.md at the top of CLAUDE.md to import it rather than duplicating its content. Claude Code only reads AGENTS.md on its own when there's no CLAUDE.md, CLAUDE.local.md, or .claude/CLAUDE.md in the working directory or above it.

Skills​

Skills use the same open Agent Skills format as Copilot: a folder with a SKILL.md and optional supporting files (scripts, templates, reference docs).

.claude/skills/release-notes/SKILL.md
---
name: release-notes
description: Drafts release notes from merged PRs since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

# Release Notes

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag with `gh pr list --state merged --search "merged:>=<tag date>"`.
3. Group changes into Features, Fixes, and Internal.
4. Follow the format in `template.md` in this folder.
  • Only name and description are loaded up front; the rest is read when the skill is used. A precise description is what makes the skill trigger.
  • A skill is also available as a slash command (/release-notes) unless its frontmatter sets user-invocable: false. Add disable-model-invocation: true for workflows that should only run when a person asks — deploys, for example.
  • Custom slash commands from .claude/commands/ still work, but skills are the current format for them.
tip

Copilot also discovers skills in .claude/skills/, so one skill folder can serve both tools.

Subagents​

A subagent runs a task in its own context window and returns only a summary. That keeps searches, log analysis, and other noisy work out of the main conversation, and lets you run the work on a cheaper model.

.claude/agents/test-runner.md
---
name: test-runner
description: Runs the test suite and reports failures with likely causes. Use after code changes or when the user asks to run tests.
tools: Bash, Read, Grep, Glob
model: haiku
---

Run `npm test`. If tests fail, read the failing test and the code under test,
and report each failure with the file, the assertion, and the most likely cause.
Do not edit files.
  • tools restricts what the subagent can do. Omit it to inherit all of the main session's tools.
  • model can be haiku, sonnet, opus, inherit, or a full model ID. If you omit it, the subagent uses the CLAUDE_CODE_SUBAGENT_MODEL environment variable when set, otherwise the main conversation's model — so set it explicitly when the point is to save cost.
  • Claude Code includes built-in subagents — such as Explore (read-only codebase search) and Plan — so check whether one fits before writing your own. The built-ins run on the main conversation's model; define your own with model: haiku to run exploration cheaply.

For the bigger picture, see Multi-Agent Orchestration and Token Consumption Optimization.

Hooks​

Hooks are shell commands that Claude Code runs at fixed points — before or after a tool call, when you submit a prompt, when Claude finishes. Unlike instructions, they always run: use them for rules that must never be skipped.

Hooks are configured in .claude/settings.json. The hook receives the event as JSON on stdin. This example formats every file Claude edits with the project's installed Prettier (it needs jq on the developer's machine):

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -j '.tool_input.file_path, \"\\u0000\"' | xargs -0 npx --no-install prettier --write"
          }
        ]
      }
    ]
  }
}

Common uses:

  • PostToolUse — format or lint files after edits
  • PreToolUse — block a tool call; a hook that exits with code 2 stops the call and shows its stderr to Claude (for example, refuse edits to package-lock.json or .env)
  • SessionStart — load dynamic context, such as the current sprint's open issues
  • Stop — run checks when Claude finishes a task
caution

Hooks run with your user permissions, without asking. Review hook commands in a repo before you start a session there, just as you would review a script before running it.

Permissions​

Permission rules in settings.json decide which tool calls run without asking, which always prompt, and which are blocked:

.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}
  • Commit a shared allowlist of safe, read-only or local commands so teammates aren't prompted for npm test every time.
  • Use deny for secret files — it is enforced by the tool, not left to the model's judgment.
  • Settings precedence, highest first: managed (organization) → command-line --settings → .claude/settings.local.json → .claude/settings.json → ~/.claude/settings.json. Rules are evaluated deny, then ask, then allow, so a deny always wins.

Claude Code also has permission modes, cycled with Shift+Tab: default (ask for each action), acceptEdits (file edits run without asking), and plan (read-only analysis, no changes). Newer builds start interactive sessions in an auto mode that approves routine actions on its own. A bypassPermissions mode that skips all prompts only joins the cycle when you enable it explicitly — keep it for sandboxed environments; see Agent Security.

MCP Servers​

Project-wide MCP servers go in .mcp.json at the repo root, using an mcpServers key:

.mcp.json
{
  "mcpServers": {
    "mdn": {
      "type": "http",
      "url": "https://mcp.mdn.mozilla.net/"
    }
  }
}

Add one from the command line with claude mcp add --transport http mdn --scope project https://mcp.mdn.mozilla.net/. Claude Code asks each developer to approve project MCP servers the first time, so a server added to the repo doesn't run silently. Use /mcp to check status and to sign in to servers that use OAuth.

See MCP Servers for which servers are worth using and how to keep secrets out of config files.

Copilot ↔ Claude Code Equivalents​

PurposeGitHub CopilotClaude Code
Project instructions.github/copilot-instructions.md or AGENTS.mdCLAUDE.md (can import @AGENTS.md)
File-scoped rules.github/instructions/*.instructions.md (applyTo)CLAUDE.md in the subfolder
Reusable workflows.github/skills/ (or .claude/skills/), *.prompt.md.claude/skills/
Specialized agents.github/agents/*.agent.md.claude/agents/*.md
Enforced automationHooks in .github/hooks/*.jsonHooks in .claude/settings.json
Tool permissionsPer-tool approval in VS Code settingspermissions in .claude/settings.json
MCP config.vscode/mcp.json (servers).mcp.json (mcpServers)

Copilot hook configuration and supported events vary by host; see the GitHub hooks reference and VS Code hooks documentation.

tip

For a team using both tools, keep shared conventions in AGENTS.md, put skills in .claude/skills/ (both tools read it), and keep only tool-specific settings in each tool's own files.

Resources​