Configuration Guide

Comprehensive guide to configuring Claude Code Tresor skills, agents, and commands.

Overview

Claude Code Tresor components are configured through:

Skills: YAML frontmatter in SKILL.md files
Agents: YAML frontmatter in SKILL.md files or agent.json
Commands: JSON configuration in command.json files

Skills Configuration

Skills are configured in ~/.claude/skills/{skill-name}/SKILL.md using YAML frontmatter.

Basic Skill Configuration

---
name: "code-reviewer"
description: "Real-time code quality and best practices checker"
trigger_keywords:
  - "save"
  - "commit"
  - "code"
  - "review"
tools:
  - "Read"
  - "Write"
  - "Edit"
  - "Grep"
  - "Glob"
model: "claude-sonnet-4"
enabled: true
priority: "high"
---

Configuration Fields

name (required)

Type: String Description: Unique identifier for the skill

name: "code-reviewer"

description (required)

Type: String Description: Human-readable description of skill purpose

description: "Real-time code quality and best practices checker"

trigger_keywords (optional)

Type: Array of strings Description: Keywords that activate the skill in conversations

trigger_keywords:
  - "save"
  - "commit"
  - "code"
  - "review"
  - "quality"

Note: Skills activate automatically based on file changes. Keywords are supplementary.

tools (required)

Type: Array of strings Description: Tools the skill can use

Available tools for skills:

Read - Read files
Write - Create/overwrite files
Edit - Modify existing files
Grep - Search file contents
Glob - Find files by pattern

Important: Skills have limited tool access for safety. No Bash or Task tools.

tools:
  - "Read"
  - "Grep"
  - "Glob"

model (optional)

Type: String Description: Claude model to use

Available models:

claude-sonnet-4 (default) - Fast, efficient
claude-opus-4 - Most capable

model: "claude-sonnet-4"

enabled (optional)

Type: Boolean Description: Enable/disable skill

enabled: true  # Skill active
enabled: false # Skill inactive

priority (optional)

Type: String Description: Execution priority

Values:

high - Execute first
medium - Default
low - Execute last

priority: "high"

file_patterns (optional)

Type: Array of glob patterns Description: File types to monitor

file_patterns:
  - "*.ts"
  - "*.tsx"
  - "*.js"
  - "*.jsx"

exclude_patterns (optional)

Type: Array of glob patterns Description: Files to ignore

exclude_patterns:
  - "node_modules/**"
  - "dist/**"
  - "*.test.ts"

Example: Custom Skill Configuration

---
name: "custom-reviewer"
description: "Custom code reviewer for React projects"
trigger_keywords:
  - "react"
  - "component"
  - "review"
tools:
  - "Read"
  - "Grep"
  - "Glob"
model: "claude-sonnet-4"
enabled: true
priority: "high"
file_patterns:
  - "*.tsx"
  - "*.jsx"
exclude_patterns:
  - "*.test.tsx"
  - "*.stories.tsx"
  - "node_modules/**"
custom_settings:
  max_file_size: "50kb"
  check_accessibility: true
  check_performance: true
---

Agents Configuration

Agents can be configured using YAML frontmatter in SKILL.md or agent.json.

Method 1: YAML Frontmatter (Recommended)

File: ~/.claude/agents/{agent-name}/SKILL.md

---
name: "code-reviewer"
description: "Expert code quality analyst"
tools:
  - "Read"
  - "Write"
  - "Edit"
  - "Grep"
  - "Glob"
  - "Bash"
  - "Task"
model: "claude-opus-4"
enabled: true
capabilities:
  - "code-analysis"
  - "security-review"
  - "performance-optimization"
---

Method 2: JSON Configuration

File: ~/.claude/agents/{agent-name}/agent.json

{
  "name": "code-reviewer",
  "description": "Expert code quality analyst",
  "tools": [
    "Read",
    "Write",
    "Edit",
    "Grep",
    "Glob",
    "Bash",
    "Task"
  ],
  "model": "claude-opus-4",
  "enabled": true,
  "capabilities": [
    "code-analysis",
    "security-review",
    "performance-optimization"
  ]
}

Agent Configuration Fields

name (required)

Type: String Description: Unique identifier (used with @agent-name)

name: "code-reviewer"

description (required)

Type: String Description: Agent's expertise and purpose

description: "Expert code quality analyst with focus on security and performance"

tools (required)

Type: Array of strings Description: Available tools

All tools available for agents:

Read, Write, Edit - File operations
Grep, Glob - Search operations
Bash - Execute commands
Task - Invoke other agents

tools:
  - "Read"
  - "Write"
  - "Edit"
  - "Grep"
  - "Glob"
  - "Bash"
  - "Task"

model (optional)

Type: String Description: Claude model

model: "claude-opus-4"  # Most capable
model: "claude-sonnet-4" # Faster

enabled (optional)

Type: Boolean

enabled: true

capabilities (optional)

Type: Array of strings Description: Agent's specialized capabilities

capabilities:
  - "code-analysis"
  - "security-review"
  - "performance-optimization"
  - "refactoring"

max_iterations (optional)

Type: Number Description: Maximum tool use iterations

max_iterations: 50

Example: Custom Agent Configuration

---
name: "custom-reviewer"
description: "Custom code reviewer for enterprise React applications"
tools:
  - "Read"
  - "Write"
  - "Edit"
  - "Grep"
  - "Glob"
  - "Bash"
  - "Task"
model: "claude-opus-4"
enabled: true
capabilities:
  - "react-analysis"
  - "typescript-validation"
  - "security-audit"
  - "performance-profiling"
  - "accessibility-check"
max_iterations: 75
custom_settings:
  frameworks:
    - "React"
    - "Next.js"
  linting_rules: "airbnb"
  security_standards: "OWASP"
---

Commands Configuration

Commands are configured in ~/.claude/commands/{command-category}/{command-name}/command.json.

Basic Command Configuration

{
  "name": "review",
  "description": "Automated code review with quality checks",
  "category": "workflow",
  "usage": "/review --scope <files> --checks <types>",
  "parameters": {
    "scope": {
      "type": "string",
      "description": "Files to review (staged, all, or file path)",
      "required": false,
      "default": "staged"
    },
    "checks": {
      "type": "array",
      "description": "Check types: security, performance, quality, all",
      "required": false,
      "default": ["all"]
    }
  },
  "agents": [
    "@code-reviewer",
    "@security-auditor",
    "@performance-tuner"
  ],
  "enabled": true
}

Command Configuration Fields

name (required)

Type: String Description: Command name (used with /command-name)

"name": "review"

description (required)

Type: String

"description": "Automated code review with quality checks"

category (required)

Type: String Description: Command category

Categories:

development - Development workflows
workflow - General workflows
testing - Testing workflows
documentation - Documentation workflows

"category": "workflow"

usage (required)

Type: String Description: Usage syntax

"usage": "/review --scope <files> --checks <types>"

parameters (optional)

Type: Object Description: Command parameters

"parameters": {
  "scope": {
    "type": "string",
    "description": "Files to review",
    "required": false,
    "default": "staged"
  },
  "checks": {
    "type": "array",
    "description": "Check types",
    "required": false,
    "default": ["all"]
  }
}

Parameter types:

string - Single value
array - Multiple values
boolean - True/false flag
number - Numeric value

agents (optional)

Type: Array of strings Description: Agents invoked by command

"agents": [
  "@code-reviewer",
  "@security-auditor",
  "@performance-tuner"
]

enabled (optional)

Type: Boolean

"enabled": true

Example: Custom Command Configuration

{
  "name": "full-audit",
  "description": "Comprehensive codebase audit with security and performance analysis",
  "category": "workflow",
  "usage": "/full-audit --path <directory> --report <format>",
  "parameters": {
    "path": {
      "type": "string",
      "description": "Directory to audit",
      "required": false,
      "default": "."
    },
    "report": {
      "type": "string",
      "description": "Report format: json, markdown, html",
      "required": false,
      "default": "markdown"
    },
    "include_tests": {
      "type": "boolean",
      "description": "Include test coverage analysis",
      "required": false,
      "default": true
    }
  },
  "agents": [
    "@code-reviewer",
    "@security-auditor",
    "@performance-tuner",
    "@test-engineer"
  ],
  "enabled": true,
  "timeout": 600,
  "output_directory": "./audit-reports"
}

Environment Variables

Configure Claude Code Tresor behavior with environment variables:

# Set default model
export CLAUDE_CODE_DEFAULT_MODEL="claude-opus-4"

# Disable specific skill
export CLAUDE_CODE_DISABLE_SKILL_code_reviewer=true

# Set skill priority
export CLAUDE_CODE_SKILL_PRIORITY_security_auditor="high"

# Enable debug mode
export CLAUDE_CODE_DEBUG=true

Advanced Configuration

Custom Skill Triggers

Configure skill activation patterns:

---
name: "api-documenter"
custom_triggers:
  file_save:
    - pattern: "src/api/**/*.ts"
      action: "generate_openapi"
  git_commit:
    - pattern: "src/controllers/*.ts"
      action: "update_api_docs"
---

Agent Coordination

Configure how agents work together:

---
name: "code-reviewer"
coordination:
  invoke_agents:
    - agent: "@security-auditor"
      when: "security_issue_detected"
    - agent: "@performance-tuner"
      when: "performance_issue_detected"
---

Command Workflows

Configure multi-step command workflows:

{
  "name": "deploy",
  "workflow": [
    {
      "step": "review",
      "command": "/review --scope all"
    },
    {
      "step": "test",
      "command": "/test-gen --coverage 90"
    },
    {
      "step": "build",
      "bash": "npm run build"
    },
    {
      "step": "deploy",
      "bash": "npm run deploy"
    }
  ]
}

Configuration Best Practices

1. Start with Defaults

Don't over-configure initially. Use defaults and customize as needed.

2. Use YAML for Readability

YAML frontmatter is more readable than JSON for complex configurations.

3. Test Configuration Changes

After changes, verify with:

# Restart Claude Code
# Test skill/agent/command

4. Document Customizations

Add comments explaining why you changed defaults:

---
name: "code-reviewer"
# Increased priority because we need immediate feedback
priority: "high"
# Added .vue files for Vue.js project
file_patterns:
  - "*.ts"
  - "*.vue"  # Vue.js components
---

5. Version Control Configuration

Commit configuration files to git for team consistency:

git add ~/.claude/skills/custom-reviewer/
git commit -m "feat: add custom code reviewer configuration"

Troubleshooting Configuration

Configuration Not Applied

Problem: Changes to configuration not taking effect

Solution:

Restart Claude Code CLI
Check syntax (YAML/JSON valid?)
Check file location (correct directory?)

Skill Not Activating

Problem: Skill configured but not activating

Solution:

Check enabled: true
Verify trigger_keywords or file_patterns
Check exclude_patterns not blocking files
Enable debug mode: export CLAUDE_CODE_DEBUG=true

Agent Not Found

Problem: @agent-name not found

Solution:

Check agent directory exists: ls ~/.claude/agents/agent-name/
Verify name field matches directory name
Check enabled: true

Next Steps

Skills Reference → - Complete skill configuration
Agents Reference → - Complete agent configuration
Commands Reference → - Complete command configuration
Troubleshooting → - Fix configuration issues

Last Updated: November 7, 2025 | Version: 2.0.0

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Configuration Guide

Overview

Skills Configuration

Basic Skill Configuration

Configuration Fields

name (required)

description (required)

trigger_keywords (optional)

tools (required)

model (optional)

enabled (optional)

priority (optional)

file_patterns (optional)

exclude_patterns (optional)

Example: Custom Skill Configuration

Agents Configuration

Method 1: YAML Frontmatter (Recommended)

Method 2: JSON Configuration

Agent Configuration Fields

name (required)

description (required)

tools (required)

model (optional)

enabled (optional)

capabilities (optional)

max_iterations (optional)

Example: Custom Agent Configuration

Commands Configuration

Basic Command Configuration

Command Configuration Fields

name (required)

description (required)

category (required)

usage (required)

parameters (optional)

agents (optional)

enabled (optional)

Example: Custom Command Configuration

Environment Variables

Advanced Configuration

Custom Skill Triggers

Agent Coordination

Command Workflows

Configuration Best Practices

1. Start with Defaults

2. Use YAML for Readability

3. Test Configuration Changes

4. Document Customizations

5. Version Control Configuration

Troubleshooting Configuration

Configuration Not Applied

Skill Not Activating

Agent Not Found

Next Steps