Initial commit
This commit is contained in:
Zhongwei Li
271
skills/configuration/SKILL.md
Normal file
271
skills/configuration/SKILL.md
Normal file
@@ -0,0 +1,271 @@
|
||||
---
|
||||
name: configuration
|
||||
description: How to configure Claude Code settings, permissions, environment variables, and project-level configurations. Use when user asks about settings.json, configuration, permissions, or Claude Code setup.
|
||||
---
|
||||
|
||||
# Claude Code Configuration
|
||||
|
||||
## Overview
|
||||
|
||||
Claude Code provides hierarchical configuration through `settings.json` files at multiple levels. You can manage settings globally, per-project, or through enterprise policies.
|
||||
|
||||
## Configuration File Locations
|
||||
|
||||
**User-level settings**: `~/.claude/settings.json` (applies to all projects)
|
||||
|
||||
**Project-level settings**:
|
||||
- `.claude/settings.json` (shared with team via source control)
|
||||
- `.claude/settings.local.json` (personal, not committed)
|
||||
|
||||
**Enterprise managed policies**:
|
||||
- macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`
|
||||
- Linux/WSL: `/etc/claude-code/managed-settings.json`
|
||||
- Windows: `C:\ProgramData\ClaudeCode\managed-settings.json`
|
||||
|
||||
## Key Configuration Options
|
||||
|
||||
| Setting | Purpose | Example |
|
||||
|---------|---------|---------|
|
||||
| `permissions` | Control tool access and file restrictions | `{"allow": ["Bash(npm run test:*)"], "deny": ["Read(.env)"]}` |
|
||||
| `env` | Environment variables for sessions | `{"FOO": "bar"}` |
|
||||
| `model` | Override default model | `"claude-sonnet-4-5-20250929"` |
|
||||
| `outputStyle` | Adjust system prompt behavior | `"Explanatory"` |
|
||||
| `hooks` | Custom commands before/after tool use | `{"PreToolUse": {"Bash": "echo 'Running..'"}}` |
|
||||
|
||||
## Permission Configuration
|
||||
|
||||
Restrict file and command access through the `permissions` object:
|
||||
|
||||
**Deny patterns** block sensitive files:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(./secrets/**)",
|
||||
"Bash(curl:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Allow patterns** explicitly permit actions:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm run lint)",
|
||||
"Bash(npm run test:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Ask patterns** require confirmation:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"ask": [
|
||||
"Bash(git push:*)",
|
||||
"Write(src/**)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sandbox Settings
|
||||
|
||||
Enable process isolation (macOS/Linux):
|
||||
|
||||
```json
|
||||
{
|
||||
"sandbox": {
|
||||
"enabled": true,
|
||||
"excludedCommands": ["docker"],
|
||||
"network": {
|
||||
"allowUnixSockets": ["~/.ssh/agent-socket"],
|
||||
"allowLocalBinding": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Settings Precedence (High to Low)
|
||||
|
||||
1. Enterprise managed policies
|
||||
2. Command-line arguments
|
||||
3. Local project settings (`.claude/settings.local.json`)
|
||||
4. Shared project settings (`.claude/settings.json`)
|
||||
5. User settings (`~/.claude/settings.json`)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Key variables for controlling Claude Code behavior:
|
||||
|
||||
- `ANTHROPIC_API_KEY` - API authentication
|
||||
- `BASH_MAX_OUTPUT_LENGTH` - Limit bash output size
|
||||
- `DISABLE_TELEMETRY` - Opt out of analytics
|
||||
- `MAX_THINKING_TOKENS` - Enable extended thinking
|
||||
- `CLAUDE_CODE_USE_BEDROCK` - Use AWS Bedrock
|
||||
- `DISABLE_PROMPT_CACHING` - Turn off caching globally
|
||||
|
||||
## Available Tools
|
||||
|
||||
Claude Code can access these tools (subject to permissions):
|
||||
- Bash
|
||||
- Edit, Read, Write
|
||||
- WebFetch, WebSearch
|
||||
- Glob, Grep
|
||||
- NotebookEdit
|
||||
- Task
|
||||
|
||||
## Plugin Management
|
||||
|
||||
Configure plugins via `enabledPlugins`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"formatter@company-tools": true,
|
||||
"deployer@company-tools": false
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"company-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "company/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Access plugin management interactively with `/plugin` command.
|
||||
|
||||
## Excluding Sensitive Files
|
||||
|
||||
Prevent Claude from accessing confidential data:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(.env)",
|
||||
"Read(.env.*)",
|
||||
"Read(./secrets/**)",
|
||||
"Read(**/credentials.json)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Files matching deny patterns become completely invisible to Claude Code.
|
||||
|
||||
## Common Configuration Examples
|
||||
|
||||
### Development Team Setup
|
||||
|
||||
**.claude/settings.json** (committed to repo):
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(npm run *)",
|
||||
"Bash(git status:*)",
|
||||
"Bash(git diff:*)"
|
||||
],
|
||||
"deny": [
|
||||
"Read(.env*)",
|
||||
"Bash(git push:*)"
|
||||
],
|
||||
"ask": [
|
||||
"Write(src/**)"
|
||||
]
|
||||
},
|
||||
"env": {
|
||||
"NODE_ENV": "development"
|
||||
},
|
||||
"extraKnownMarketplaces": {
|
||||
"team-tools": {
|
||||
"source": {
|
||||
"source": "github",
|
||||
"repo": "your-org/claude-plugins"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Personal Overrides
|
||||
|
||||
**.claude/settings.local.json** (not committed):
|
||||
```json
|
||||
{
|
||||
"model": "claude-opus-4-5-20250514",
|
||||
"env": {
|
||||
"CUSTOM_VAR": "my-value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enterprise Security Policy
|
||||
|
||||
**/etc/claude-code/managed-settings.json**:
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(/etc/passwd)",
|
||||
"Read(~/.ssh/**)",
|
||||
"Bash(rm:*)",
|
||||
"Bash(sudo:*)"
|
||||
]
|
||||
},
|
||||
"sandbox": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Managing Settings
|
||||
|
||||
**View current settings**: Check the files in `.claude/` directory
|
||||
|
||||
**Edit project settings**: Create or modify `.claude/settings.json`
|
||||
|
||||
**Edit user settings**: Modify `~/.claude/settings.json`
|
||||
|
||||
**Interactive configuration**: Some settings can be managed via slash commands like `/permissions`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use project settings** for team-shared configuration
|
||||
2. **Use local settings** for personal preferences
|
||||
3. **Commit shared settings** to source control
|
||||
4. **Document settings** with comments (use `//` in JSON5-compatible editors)
|
||||
5. **Review permissions** regularly for security
|
||||
6. **Test settings** before enforcing team-wide
|
||||
7. **Use deny patterns** for sensitive files
|
||||
8. **Enable sandbox** for additional security
|
||||
9. **Set environment variables** for consistent environments
|
||||
10. **Configure marketplaces** for team plugin distribution
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Settings not applying:**
|
||||
- Check file locations and names
|
||||
- Verify JSON syntax
|
||||
- Review precedence order
|
||||
- Check for conflicting settings at different levels
|
||||
|
||||
**Permission errors:**
|
||||
- Review deny/allow patterns
|
||||
- Check pattern syntax (glob patterns supported)
|
||||
- Verify file paths are correct
|
||||
- Test patterns incrementally
|
||||
|
||||
**Plugin issues:**
|
||||
- Verify marketplace configuration
|
||||
- Check plugin names and versions
|
||||
- Ensure plugins are enabled in `enabledPlugins`
|
||||
- Review plugin-specific settings
|
||||
Reference in New Issue
Block a user