Reviewing Claude Config

Reviewing Claude Configuration

Instructions

IMPORTANT: Use structured thinking throughout your review process. Plan your analysis before providing feedback. This improves accuracy and catches critical security issues.

Step 1: Detect File Type

<thinking> Analyze the changed files: 1. Which .claude files were modified? 2. What file types? (CLAUDE.md, skills, agents, prompts, commands, settings) 3. Are there immediate security concerns? 4. What's the review scope (single file or multiple)? </thinking>

Determine the primary file type(s) being reviewed:

Detection Rules:

• Agents: Changes to .claude/agents/*.md or plugins/*/agents/*.md
• Skills: Changes to skill.md files or skill support files (checklists, references, examples)
• CLAUDE.md: Changes to CLAUDE.md files (any location: project root, .claude/, or subdirectories)
• Prompts/Commands: Changes to .claude/prompts/*.md or .claude/commands/*.md
• Settings: Changes to .claude/settings.json or .claude/settings.local.json

If multiple types modified, review each with appropriate checklist.

Step 2: Execute Security Scan (ALWAYS)

<thinking> Security first, regardless of file type: 1. Is settings.local.json committed to git? 2. Any hardcoded secrets (passwords, tokens, API keys)? 3. Are permissions appropriately scoped (if settings modified)? 4. Any suspicious patterns in changed files? </thinking>

CRITICAL CHECKS (perform for ALL Claude config reviews):

Run these mental checks immediately:

• [ ] settings.local.json NOT in git (check changed files list)
• [ ] No hardcoded credentials in any modified files
• [ ] Permissions scoped appropriately (if settings.json modified)
• [ ] No API keys, tokens, or passwords in plaintext

If ANY security issue found: Flag as CRITICAL immediately, stop and report.

Consult reference/security-patterns.md for detailed security checks and detection commands.

Step 3: Load Appropriate Checklist

Based on detected file type, read and follow the relevant checklist:

• Agents → checklists/agents.md (YAML, tool access security, model selection, system prompts)
• Skills → checklists/skills.md (structure, YAML, progressive disclosure, quality)
• CLAUDE.md → checklists/claude-md.md (clarity, references, no duplication)
• Prompts/Commands → checklists/prompts.md (purpose, session context, skill references)
• Settings → checklists/settings.md (security, permissions scoping)

The checklist provides:

• Multi-pass review strategy
• What to check and what to skip
• Structured thinking guidance
• Common issues and red flags

Step 4: Consult Reference Materials As Needed

<thinking> When to load references: 1. Need to classify issue priority? → priority-framework.md 2. Security patterns unclear? → security-patterns.md 3. Claude Code requirements (YAML, tools, models, limits)? → claude-code-requirements.md </thinking>

Load reference files only when needed for specific questions:

• Issue prioritization → reference/priority-framework.md (CRITICAL vs IMPORTANT vs SUGGESTED vs OPTIONAL)
• Security patterns → reference/security-patterns.md (detection commands, fix examples)
• Claude Code requirements → reference/claude-code-requirements.md (YAML frontmatter, model selection, tool names, progressive disclosure, settings conventions)

Step 5: Document Findings

<thinking> Before writing each comment: 1. Priority level? (Critical/Important/Suggested/Optional) 2. Security issue or quality issue? 3. What's the specific fix or recommendation? 4. What's the rationale (why does this matter)? 5. Is there a reference or documentation link? </thinking>

This section defines the standard output format for ALL Claude config reviews. Checklists reference this section rather than duplicating content.

CRITICAL: Use inline comments on specific lines, NOT one large summary comment.

Inline Comment Rules:

• Create separate comment for EACH specific issue on the exact line
• Do NOT create one large summary comment with all issues
• Do NOT update existing comments - always create new comments
• Include specific fix with code example when applicable
• Explain rationale (why this matters)

Comment Format:

**[file:line]** - [PRIORITY]: [Issue description]

[Specific fix with code example if applicable]

[Rationale explaining why this matters]

Reference: [documentation link if applicable]

Example inline comment:

```` .claude/skills/my-skill/skill.md:1 - CRITICAL: Missing YAML frontmatter

Skills require YAML frontmatter to be discoverable by Claude Code:

\``yaml --- name: my-skill description: Clear description with activation triggers --- \``

Without frontmatter, the skill won't be recognized by Claude Code.

Reference: Anthropic Skills Documentation ````

When to use inline vs summary:

• Inline comment: Specific issue, recommendation, or question (use file:line format)
• Summary comment: Overall assessment, recommendation (APPROVE or REQUEST CHANGES)

Load the specific example relevant to your file type (on-demand only, not upfront):

• Agents → examples/example-agent-review.md
• Skills → examples/example-skill-review.md
• CLAUDE.md → examples/example-claude-md-review.md
• Settings → examples/example-settings-review.md
• Prompts → examples/example-prompts-review.md

Cross-Plugin Enrichment

Enhanced Secret Detection (bitwarden-security-engineer plugin)

When the bitwarden-security-engineer plugin is installed, supplement the manual security scan above with:

• Comprehensive secret patterns → activate Skill(detecting-secrets) for context-aware detection that distinguishes test fixtures from production secrets, and covers patterns beyond the manual checks above (connection strings, private keys, cloud provider tokens)

This skill is optional. If unavailable, rely on the manual security checks above.

Core Principles

• Security first: Always check for committed settings, secrets, overly broad permissions
• Structure matters: YAML frontmatter, file references, progressive disclosure, line limits
• Quality counts: Clear instructions, examples, proper emphasis, structured thinking
• Token efficiency: Progressive disclosure, appropriate file sizes, on-demand loading
• Actionable feedback: Say what to do and why, not just what's wrong
• Constructive tone: Focus on code/config, not people; explain rationale

Agents Review Checklist

Review checklist for changes to Claude Code agent files (.claude/agents/*.md and plugins/*/agents/*.md).

---

Multi-Pass Review Strategy

First Pass: Structure and YAML Frontmatter

<thinking> Critical structural elements for agents: 1. Is YAML frontmatter present and valid? 2. Are required fields (name, description) present? 3. Are optional fields (tools, model) valid if present? 4. Does the agent file have a system prompt? 5. Is the basic structure sound? </thinking>

Focus Areas:

• [ ] YAML frontmatter present and syntactically valid
• [ ] Required fields: name and description
• [ ] Optional fields validated if present: tools, model
• [ ] System prompt exists and is non-empty
• [ ] File structure follows markdown format

Required YAML Frontmatter:

---
name: agent-name-in-lowercase-with-hyphens
description: Specific description with activation triggers
---

Optional YAML Fields:

---
name: agent-name
description: Clear description
tools: Read, Grep, Glob # Comma-separated tool names (omit to inherit all)
model: sonnet # Options: sonnet, opus, haiku, inherit
---

Critical Issues to Flag Immediately:

• Missing YAML frontmatter (agent won't be recognized)
• Missing name field
• Missing description field
• Invalid YAML syntax (tabs, malformed structure)
• Invalid model value (must be: sonnet, opus, haiku, inherit)
• Invalid tool names in tools field
• Empty system prompt

Reference: Anthropic - Claude Code Subagents Documentation

---

Second Pass: Security and Tool Access

<thinking> Security implications of agent configuration: 1. What tools does this agent have access to? 2. Is tool access scoped by principle of least privilege? 3. Are there dangerous tool combinations? 4. Could this agent perform unintended destructive operations? 5. Is tool access justified by agent purpose? </thinking>

Principle of Least Privilege: Agents should have ONLY the tools necessary for their specific function.

Tool Access Patterns:

✅ GOOD - Read-only analysis agent:

---
name: code-analyzer
description: Analyzes code quality and patterns
tools: Read, Grep, Glob
---

✅ GOOD - Scoped editing agent:

---
name: test-generator
description: Generates unit tests for existing code
tools: Read, Grep, Write
---

❌ BAD - Overly broad access:

---
name: helper-agent
description: Helps with various tasks
# No tools field = inherits ALL tools
---

❌ BAD - Unnecessary destructive access:

---
name: documentation-writer
description: Writes documentation
tools: Read, Write, Edit, Bash # Why does documentation need Bash?
---

Security Checks:

• [ ] Tool access scoped to minimum required
• [ ] Read-only agents don't have Write/Edit/Bash
• [ ] Bash access is justified for agent purpose
• [ ] If tools omitted (inherits all), this is intentional and documented
• [ ] No dangerous tool combinations without justification

Common Secure Patterns:

• Analyst/Reviewer: Read, Grep, Glob (read-only)
• Code Generator: Read, Grep, Write (creates new files)
• Refactoring Agent: Read, Grep, Edit (modifies existing)
• Automation Agent: Read, Write, Bash (needs command execution)

Red Flags:

• Inheriting all tools without clear justification
• Bash access without explanation
• Write/Edit access for analysis-only agents
• Tool access mismatched to agent description

Reference: reference/claude-code-requirements.md - Tool Access Security (lines 109-133)

---

Third Pass: Description and Activation Triggers

<thinking> Description quality considerations: 1. Is it clear what this agent does? 2. When should Claude invoke this agent? 3. Are activation triggers specific? 4. Can users understand when to use this agent? 5. Is the description too vague or too verbose? </thinking>

Effective Descriptions: Descriptions must be specific about BOTH functionality AND activation triggers.

✅ GOOD - Specific with activation triggers:

description: Reviews Kotlin code for MVVM violations, state management issues, and Compose best practices. Use when analyzing Android ViewModels, state flows, or Compose UI code.

✅ GOOD - Clear automatic delegation:

description: Debugs runtime errors by analyzing stack traces and logs. PROACTIVELY invoke when error messages or exceptions are present.

✅ GOOD - Narrow scope with examples:

description: Generates unit tests for Python functions using pytest. Use when working with .py files that lack test coverage.

❌ BAD - Too vague:

description: Helps with code stuff.

❌ BAD - No activation triggers:

description: Analyzes code quality and suggests improvements.
# When should this be used? What languages? What types of improvements?

❌ BAD - Too broad (violates single responsibility):

description: Handles all aspects of development including coding, testing, deployment, documentation, and architecture design.

Check For:

• [ ] Description states what the agent does
• [ ] Description includes activation triggers (when to use)
• [ ] Description is specific, not vague
• [ ] Single responsibility (focused scope)
• [ ] Appropriate level of detail (not too terse, not too verbose)

Activation Language Patterns:

• "Use when..." - Explicit trigger conditions
• "PROACTIVELY invoke..." - Encourages automatic delegation
• "Use for..." - Specific use cases
• Language/framework specific - Improves targeting

---

Fourth Pass: System Prompt Quality

<thinking> System prompt effectiveness: 1. Are instructions clear and specific? 2. Does it define role and capabilities? 3. Are examples provided for complex behaviors? 4. Does it include constraints and boundaries? 5. Is structured thinking guidance present? 6. Is the prompt token-efficient? </thinking>

System Prompt Requirements:

Clarity and Specificity:

• [ ] Role clearly defined
• [ ] Capabilities explicitly stated
• [ ] Constraints and boundaries documented
• [ ] Expected behavior specified
• [ ] Output format defined (if applicable)

Prompt Engineering Best Practices:

✅ GOOD - Structured with examples:

# Code Reviewer Agent

## Role

You are a specialized code reviewer focusing on security vulnerabilities, performance issues, and adherence to SOLID principles.

## Capabilities

- Identify SQL injection, XSS, and CSRF vulnerabilities
- Detect performance anti-patterns (N+1 queries, memory leaks)
- Verify SOLID principle adherence

## Process

1. Read the file and understand context
2. Analyze against security checklist
3. Check performance patterns
4. Verify architectural principles
5. Provide inline comments with file:line references

## Output Format

**file.py:42** - CRITICAL: SQL injection vulnerability
[Specific fix with code example]
[Rationale explaining security impact]

## Examples

[Include 2-3 examples of good review comments]

✅ GOOD - Includes structured thinking:

Before analyzing each file, use structured thinking:

<thinking>
1. What is the file's purpose?
2. What are the main security risks for this type of code?
3. What performance patterns should I check?
4. Are there obvious SOLID violations?
</thinking>

Then provide your analysis...

❌ BAD - Too vague:

Review code and find problems.

❌ BAD - No structure or examples:

You're a code reviewer. Look at code and tell the user what's wrong with it. Check for bugs and bad practices.

Structured Thinking Guidance:

• [ ] <thinking> blocks guide reasoning process
• [ ] Key questions posed for each major step
• [ ] Decision criteria made explicit
• [ ] Systematic analysis approach modeled

Token Efficiency:

• [ ] Concise without losing clarity
• [ ] Examples are minimal but sufficient
• [ ] No unnecessary verbosity
• [ ] Direct language preferred

Reference: Anthropic Chain of Thought documentation (40% error reduction with structured thinking)

---

Fifth Pass: Model Selection and Best Practices

<thinking> Model selection considerations: 1. Is the model field specified? 2. If specified, is the selection appropriate for task complexity? 3. Should this use haiku for speed or sonnet for quality? 4. Is 'inherit' used appropriately? 5. Does the agent follow single responsibility principle? </thinking>

Model Selection Guidance:

model: haiku   # Fast, cost-effective for simple tasks
model: sonnet  # Balanced for most tasks (default)
model: opus    # Most capable, use sparingly for complex reasoning
model: inherit # Inherits from parent conversation

When to Use Each Model:

Haiku - Simple, straightforward tasks:

• Formatting code
• Running predefined scripts
• Simple file operations
• Quick analysis with clear criteria

Sonnet - Most agent tasks (default):

• Code review
• Bug analysis
• Test generation
• Documentation writing
• Moderate complexity reasoning

Opus - Complex reasoning only:

• Architectural decisions
• Complex refactoring across multiple files
• Novel problem-solving
• High-stakes analysis requiring maximum accuracy

Inherit - Context-dependent:

• When agent needs same context as main conversation
• When model selection should match user's choice
• For consistency across conversation

Best Practice Checks:

• [ ] Model specified or intentionally omitted
• [ ] Model complexity matches task complexity
• [ ] Not using opus unnecessarily (cost/latency)
• [ ] Haiku used where speed matters and task is simple
• [ ] Single responsibility principle followed
• [ ] Agent scope appropriately focused

Anti-Patterns:

• Using opus for simple formatting tasks
• Using haiku for complex analysis
• Agent trying to handle too many different task types
• Model selection not documented/justified

Reference: Anthropic - Subagent Configuration Best Practices

---

Sixth Pass: Plugin Marketplace Standards

<thinking> Marketplace quality considerations: 1. Is this agent part of a plugin? 2. If marketplace-bound, does it meet quality standards? 3. Is documentation comprehensive? 4. Are examples included? 5. Is the agent production-ready? </thinking>

For Marketplace-Bound Agents:

Elevated Standards:

• Missing examples: SUGGESTED → IMPORTANT
• Vague descriptions: IMPORTANT → CRITICAL
• Poor system prompt: SUGGESTED → IMPORTANT
• Undocumented tool access: IMPORTANT → CRITICAL

Documentation Requirements:

• [ ] Clear purpose and use cases
• [ ] Examples in system prompt
• [ ] Tool access justified
• [ ] Model selection explained
• [ ] Expected outputs demonstrated

Production Readiness:

• [ ] Error handling considered
• [ ] Edge cases addressed
• [ ] Clear success/failure criteria
• [ ] Graceful degradation patterns

Internal vs Marketplace:

• Internal agents: Can accept more SUGGESTED issues
• Marketplace agents: Must fix all IMPORTANT issues
• Both: Must fix all CRITICAL security/functionality issues

---

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren't essential
• OPTIONAL - Personal preferences

---

Common Agent Anti-Patterns

Over-Privileged Agent:

• Inherits all tools without justification
• Bash access for read-only task
• Fix: Specify minimum required tools

Vague Purpose:

• Description: "Helps with code"
• Better: "Reviews Python code for PEP 8 violations. Use when analyzing .py files."

Missing Structured Thinking:

• System prompt lacks reasoning guidance
• No decision criteria for complex choices
• Fix: Add <thinking> blocks with key questions

Wrong Model Selection:

• Using opus for simple formatting
• Using haiku for complex analysis
• Fix: Match model to task complexity

Scope Creep:

• Agent trying to handle multiple unrelated tasks
• Jack-of-all-trades, master of none
• Fix: Split into focused, single-purpose agents

Security Oversights:

• Bash access without scoping
• Write access for analysis-only agents
• No consideration of tool access implications
• Fix: Apply principle of least privilege

---

Final Checklist Summary

Before completing review, verify:

• [ ] YAML frontmatter present and valid
• [ ] Required fields (name, description) present
• [ ] Optional fields valid if present
• [ ] Tool access follows least privilege
• [ ] Description includes activation triggers
• [ ] System prompt is clear and specific
• [ ] Model selection appropriate for task
• [ ] Single responsibility principle followed
• [ ] Security implications considered
• [ ] Marketplace standards met (if applicable)

CLAUDE.md Review Checklist

Review checklist for changes to CLAUDE.md files at any level (project root, .claude/ directory, or subdirectories).

Valid CLAUDE.md Locations:

• Project root: /CLAUDE.md - Global project instructions
• Claude directory: /.claude/CLAUDE.md - Claude Code-specific instructions
• Subdirectories: /path/to/subdirectory/CLAUDE.md - Scoped instructions for specific modules/components

All locations are valid and serve different scoping purposes. This checklist applies equally to all locations.

---

Multi-Pass Review Strategy

First Pass: Security and Permissions

<thinking> Security considerations for CLAUDE.md: 1. Are there any hardcoded credentials or secrets? 2. Are file permissions appropriately scoped? 3. Are there references to sensitive paths that shouldn't be exposed? 4. If auto-approved commands listed, are they safe? </thinking>

Critical Security Checks:

• [ ] No hardcoded API keys, tokens, or passwords
• [ ] No sensitive environment variables exposed
• [ ] No overly broad file permissions (e.g., Read:/\*)
• [ ] No dangerous auto-approved commands (rm -rf, etc.)
• [ ] No paths exposing sensitive user data

Common Security Issues:

❌ BAD: apiKey: "sk-1234567890abcdef"
✅ GOOD: Reference: Use environment variable $API_KEY

❌ BAD: Auto-approve: Bash(rm -rf:_)
✅ GOOD: Auto-approve: Bash(npm install:_)

❌ BAD: Read://Users/username/.ssh/**
✅ GOOD: Read://Users/username/projects/myproject/**

---

Second Pass: Structure and Clarity

<thinking> CLAUDE.md structure considerations: 1. Are directives clearly stated and prioritized? 2. Is information organized logically? 3. Are references to other docs used instead of duplication? 4. Is the purpose of each section clear? </thinking>

Organizational Requirements:

• [ ] Clear section headers organize content
• [ ] Core directives stated upfront
• [ ] References to detailed docs (not duplication)
• [ ] Logical flow from general to specific
• [ ] Purpose of file is immediately clear

Example Structure:

# Project Guidelines

Core directives for [project purpose].

## Core Directives

[High-level must-follow rules]

## Code Quality Standards

[Brief standards, reference detailed docs]

## Workflow Practices

[How to approach tasks]

## Reference Documentation

[Links to detailed architecture/style docs]

Red Flags:

• No clear organization or section headers
• Mixing high-level directives with low-level details
• Duplicating content from other documentation files
• Unclear what the core requirements are

---

Third Pass: Avoid Duplication

<thinking> Duplication check: 1. Is content copied from other documentation files? 2. Are there references to source docs instead of duplication? 3. If something is detailed elsewhere, is it just linked? 4. Are core directives vs detailed specs properly separated? </thinking>

Anti-Pattern: Duplicating Architecture Docs

❌ BAD - Copying detailed patterns into CLAUDE.md:

## MVVM Pattern

ViewModels must expose StateFlow...
[500 lines of detailed MVVM guidance]

✅ GOOD - Reference detailed docs:

## Core Directives

1. Adhere to Architecture: All code MUST follow `docs/ARCHITECTURE.md`
2. Follow Code Style: ALWAYS follow `docs/STYLE_AND_BEST_PRACTICES.md`

Principle: CLAUDE.md provides high-level directives and references. Detailed specs live in their own documentation files.

Appropriate Content:

• Core must-follow directives
• Workflow practices (before/during/after implementation)
• Decision-making guidance (when to ask vs proceed)
• References to detailed documentation

Inappropriate Content:

• Detailed API documentation (belongs in code docs)
• Complete architecture patterns (belongs in ARCHITECTURE.md)
• Full style guide (belongs in STYLE_AND_BEST_PRACTICES.md)
• Library-specific usage (belongs in library docs)

---

Fourth Pass: Clarity and Actionability

<thinking> Clarity considerations: 1. Are directives specific and actionable? 2. Is it clear WHEN each directive applies? 3. Are examples provided for ambiguous concepts? 4. Is the tone appropriate (directive vs suggestive)? </thinking>

Specific vs Vague Directives:

❌ VAGUE: "Write good code" ✅ SPECIFIC: "Follow Kotlin idioms: immutability, appropriate data structures, coroutines"

❌ VAGUE: "Test your changes" ✅ SPECIFIC: "All code must pass testing rites before deployment liturgies commence"

❌ VAGUE: "Use dependency injection" ✅ SPECIFIC: "Use Hilt DI patterns: @Inject constructor, interface injection, @HiltViewModel"

Actionable Decision Guidance:

✅ GOOD - Clear when to ask vs proceed:

## Decision-Making

Defer to user for high-impact decisions:

- Architecture/module changes
- Public API modifications
- Security mechanism changes
- Database migrations
- Third-party library additions

Proceed autonomously for:

- Implementation details within established patterns
- Test additions
- Documentation updates
- Bug fixes following existing patterns

---

Fifth Pass: Token Efficiency

<thinking> Token efficiency for CLAUDE.md: 1. Is the file concise without losing critical information? 2. Are references used instead of duplication? 3. Is verbose language minimized? 4. Is information organized for quick scanning? </thinking>

Efficiency Techniques:

Use References:

Reference Documentation:

- `docs/ARCHITECTURE.md` - Architecture patterns
- `docs/STYLE_AND_BEST_PRACTICES.md` - Code style

Do not duplicate information from these files.

Use Lists and Headers:

Anti-Patterns:

- Creating new patterns when established ones exist
- Exception-based error handling in business logic
- Direct dependency access (use DI)

Be Concise: ❌ "It is very important that you should always make sure to..." ✅ "Always..."

---

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren't essential
• OPTIONAL - Personal preferences

---

Prompts and Commands Review Checklist

Review checklist for changes to .claude/prompts/*.md and .claude/commands/*.md files.

---

Multi-Pass Review Strategy

First Pass: Purpose and Activation

<thinking> Purpose clarity: 1. Is it clear what this prompt/command does? 2. When should it be invoked? 3. What input does it expect? 4. What output will it produce? </thinking>

Clear Purpose Statement: Every prompt/command file should answer these questions in first 1-3 lines:

# Command Name

Brief description of what this does and when to use it.

Examples:

✅ GOOD - Clear purpose:

# review-pr

Reviews a GitHub pull request by number. Use when analyzing PR changes before merge.

Usage: /review-pr <pr-number>

❌ BAD - Vague purpose:

# review-pr

Does PR stuff.

---

Second Pass: Completeness

<thinking> Completeness check: 1. Does the prompt provide all necessary context? 2. Are expected outputs clearly defined? 3. Are examples provided where helpful? 4. Is the prompt self-contained or properly referencing skills? </thinking>

Complete Prompt Elements:

• [ ] Clear description of task
• [ ] Expected input format (if applicable)
• [ ] Expected output format
• [ ] Examples (if task is complex)
• [ ] References to relevant skills or documentation

Self-Contained vs Skill Reference:

✅ GOOD - Simple task, self-contained:

# format-commit

Generate a conventional commit message from staged changes.

Format: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore

✅ GOOD - Complex task, reference skill:

# review-changes

Review current git changes for code quality and architectural compliance.

Use the `reviewing-changes` skill to perform comprehensive review based on change type.

❌ BAD - Complex task without guidance:

# review-changes

Review the code.

---

Third Pass: Prompt Engineering Quality

<thinking> Quality considerations: 1. Is the language clear and specific? 2. Are instructions structured logically? 3. Are examples provided for complex concepts? 4. Does it use appropriate emphasis? </thinking>

Clarity and Specificity:

❌ VAGUE: "Look at the files and find problems" ✅ SPECIFIC: "Analyze modified Kotlin files for MVVM violations: mutable state exposure, improper dependency injection, missing error handling"

Logical Structure:

✅ GOOD - Step-by-step:

1. Read the PR description and changed files
2. Identify the change type (feature, bug fix, refactor)
3. Apply appropriate review checklist
4. Document findings with inline comments

Examples for Complex Tasks:

✅ GOOD - Shows expected format:

````markdown Expected output format:

\``` file.kt:123 - CRITICAL: Exposes mutable state

Change MutableStateFlow to StateFlow: ... \`` ```

---

Fourth Pass: Session Context

<thinking> Session context considerations: 1. Does this prompt make assumptions about session state? 2. Does it require files to be read first? 3. Does it handle missing context gracefully? 4. Is it clear what the user needs to provide? </thinking>

Context Requirements:

✅ GOOD - Explicit about requirements:

# review-file

Reviews a specific file for quality issues.

**Usage:** /review-file path/to/file.kt

This command will read the file and analyze it against project standards.

❌ BAD - Assumes context without stating:

# review-file

Reviews the file.

Graceful Handling:

✅ GOOD - Handles missing info:

If no PR number provided, analyze current git diff.
If no files changed, report clean working directory.

---

Fifth Pass: Skill References

<thinking> Skill reference check: 1. If this references a skill, does the skill exist? 2. Is the skill name correct? 3. Is it clear when to use command vs skill directly? 4. Is the relationship between command and skill logical? </thinking>

Proper Skill References:

✅ GOOD - Clear skill invocation:

# review-changes

Use the `reviewing-changes` skill to perform comprehensive code review.

This command is equivalent to directly invoking the skill but provides
a convenient shorthand for PR and commit reviews.

Verify:

• [ ] Referenced skill exists in .claude/skills/
• [ ] Skill name matches exactly (case-sensitive)
• [ ] Command adds value beyond just calling skill
• [ ] Command purpose is distinct from skill purpose

---

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren't essential
• OPTIONAL - Personal preferences

---

Settings Review Checklist

Review checklist for changes to .claude/settings.json and .claude/settings.local.json.

---

CRITICAL SECURITY CHECK

<thinking> CRITICAL security considerations: 1. Is settings.local.json committed to git? 2. Are there hardcoded credentials or secrets? 3. Are file permissions overly broad? 4. Are command auto-approvals safe? </thinking>

Before anything else, verify:

• [ ] settings.local.json is NOT committed to git
• [ ] No hardcoded API keys, tokens, or passwords
• [ ] No sensitive paths exposed in permissions
• [ ] No dangerous command auto-approvals

If ANY of these fail, FLAG IMMEDIATELY as CRITICAL and stop review.

---

Multi-Pass Review Strategy

First Pass: Committed Settings Detection

CRITICAL SECURITY ISSUE: settings.local.json in git

settings.local.json must NEVER be committed. It contains user-specific and potentially sensitive configuration.

Detection: Check if settings.local.json appears in changed files list. If present in git diff or PR, this is CRITICAL.

Fix:

# Remove from git but keep locally
git rm --cached .claude/settings.local.json

# Ensure .gitignore includes it
echo ".claude/settings.local.json" >> .gitignore

Rationale: Local settings may contain:

• User-specific file paths
• API keys or tokens
• Personal preferences
• Machine-specific configuration

Committing these exposes sensitive data and creates conflicts between users.

---

Second Pass: Hardcoded Secrets

<thinking> Secret detection: 1. Are there API keys in plaintext? 2. Are there passwords or tokens? 3. Are there authentication credentials? 4. Should any values be environment variables instead? </thinking>

Scan for Common Secret Patterns:

❌ CRITICAL ISSUES:

{
  "apiKey": "sk-1234567890abcdef",
  "password": "mypassword123",
  "token": "ghp_xxxxxxxxxxxx",
  "secret": "shared-secret-value"
}

✅ SAFE ALTERNATIVES:

{
  "apiKeyVar": "$OPENAI_API_KEY",
  "authMethod": "environment",
  "note": "Set API key in environment: export OPENAI_API_KEY=xxx"
}

Common Secret Patterns:

• apiKey, api_key, API_KEY
• password, passwd, pwd
• token, auth_token, access_token
• secret, shared_secret
• Keys starting with sk-, ghp_, gho_, etc.

---

Third Pass: Permission Scoping

<thinking> Permission scoping: 1. Are file permissions appropriately limited? 2. Are read permissions scoped to project directories? 3. Are write permissions even more restrictive? 4. Are there any wildcard patterns that are too broad? </thinking>

Appropriate Permission Scoping:

❌ TOO BROAD:

{
  "autoApprovedTools": ["Read://*", "Write://*", "Bash:*"]
}

✅ APPROPRIATELY SCOPED:

{
  "autoApprovedTools": [
    "Read://Users/username/projects/myproject/**",
    "Write://Users/username/projects/myproject/src/**",
    "Bash:git status:*",
    "Bash:npm install:*"
  ]
}

Permission Guidelines:

Read Permissions:

• Scope to project directory and relevant config
• Avoid Read://* (entire filesystem)
• Consider what actually needs to be read

Write Permissions:

• Even more restrictive than Read
• Limit to source directories, not config or root
• Avoid write access outside project

Bash Permissions:

• Specific commands, not Bash:*
• Safe operations: git status, npm install, ./gradlew test
• NEVER auto-approve: rm -rf, dd, chmod 777, curl | sh

---

Fourth Pass: Command Auto-Approval Safety

<thinking> Command safety: 1. Are auto-approved commands safe to run? 2. Could they cause data loss or system damage? 3. Are they read-only or idempotent? 4. Should any require explicit approval? </thinking>

Safe vs Dangerous Commands:

✅ SAFE to auto-approve:

{
  "autoApprovedTools": [
    "Bash:git status:*",
    "Bash:git log:*",
    "Bash:git diff:*",
    "Bash:./gradlew test:*",
    "Bash:npm install:*",
    "Bash:ls:*"
  ]
}

❌ DANGEROUS - require approval:

{
  "autoApprovedTools": [
    "Bash:rm -rf:*", // Data destruction
    "Bash:git push --force:*", // Destructive git operation
    "Bash:chmod 777:*", // Security risk
    "Bash:curl * | sh:*", // Arbitrary code execution
    "Bash:dd:*", // Low-level disk operations
    "Bash:mkfs:*" // Filesystem formatting
  ]
}

Safety Criteria:

• Read-only operations: Generally safe (ls, git status, git diff)
• Idempotent operations: Safe to run multiple times (npm install, git pull)
• Destructive operations: Require approval (rm, force push, formatting)
• External code execution: Require approval (curl | sh, wget | bash)

---

Fifth Pass: JSON Syntax and Structure

<thinking> Syntax validation: 1. Is the JSON valid (no trailing commas, proper quotes)? 2. Are field names correct (check documentation)? 3. Are values the right type (string vs array vs boolean)? 4. Is the structure logical and organized? </thinking>

Common JSON Issues:

❌ Syntax errors:

{
  "autoApprovedTools": [
    "Read://path/**" // Trailing comma error
  ]
}

✅ Valid JSON:

{
  "autoApprovedTools": ["Read://path/**"]
}

Field Validation:

• Check field names against Claude Code documentation
• Verify value types (string, boolean, array, object)
• Ensure required fields are present
• Remove unknown or deprecated fields

---

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren't essential
• OPTIONAL - Personal preferences

---

Skills Review Checklist

Review checklist for changes to Claude Code skill files (SKILL.md and supporting files).

---

Multi-Pass Review Strategy

First Pass: Structure and Security

<thinking> Critical structural elements: 1. Is YAML frontmatter present and valid? 2. Is the skill file within 500 line limit? 3. Are there any security issues (hardcoded secrets, committed settings)? 4. Do all file references point to existing files? 5. Is progressive disclosure properly implemented? </thinking>

Focus Areas:

• [ ] YAML frontmatter present and valid
• [ ] Skill file size ≤ 500 lines (progressive disclosure requirement)
• [ ] No hardcoded secrets or credentials
• [ ] File references point to existing files
• [ ] Supporting files are properly organized

Critical Issues to Flag Immediately:

• Missing YAML frontmatter (skill won't be recognized)
• File > 500 lines without progressive disclosure
• Hardcoded API keys, tokens, or passwords
• Broken file references
• Committed settings.local.json

---

Second Pass: YAML Frontmatter Validation

<thinking> YAML frontmatter requirements: 1. Is the name field present and kebab-case? 2. Is the description clear with activation triggers? 3. If versioned, does it follow semver? 4. Are there any malformed YAML syntax issues? </thinking>

Required Fields:

---
name: skill-name-in-kebab-case
description: Clear description with activation triggers
---

Optional Fields:

version: 1.0.0 # Semver format if marketplace-bound

Check For:

• [ ] name field exists and is kebab-case
• [ ] description field exists and is clear
• [ ] Description includes activation triggers (when to use)
• [ ] YAML syntax is valid (proper indentation, no tabs)
• [ ] If versioned, follows semver (MAJOR.MINOR.PATCH)

Common Issues:

• Missing name or description
• Name not in kebab-case (use-dashes-not-underscores)
• Description too vague ("does stuff" → specify what and when)
• Malformed YAML (tabs instead of spaces, missing colons)

---

Third Pass: Progressive Disclosure

<thinking> Progressive disclosure requirements: 1. Is the main skill.md file under 500 lines? 2. Are supporting files properly referenced? 3. Are supporting files self-contained? 4. Is the loading strategy clear (when to load what)? </thinking>

Main skill.md Requirements:

• [ ] File size ≤ 500 lines
• [ ] Clear routing logic (when to load which files)
• [ ] Structured thinking blocks guide decision-making
• [ ] References supporting files explicitly

Supporting Files Requirements:

• [ ] Each file is self-contained (understandable in isolation)
• [ ] Clear purpose stated at top of file
• [ ] No circular dependencies between files
• [ ] Loaded on-demand, not all at once

File Organization Patterns:

skill-name/
├── skill.md              # Main orchestration (≤500 lines)
├── checklists/           # Task-specific procedures
├── reference/            # Detailed criteria loaded as needed
├── examples/             # Sample outputs for guidance
└── scripts/              # Executable automation (if applicable)

Red Flags:

• Main skill.md > 500 lines (should be split into supporting files)
• Supporting files reference each other in circles
• All context loaded upfront instead of on-demand
• Supporting files not self-contained (require reading multiple files)

---

Fourth Pass: Prompt Engineering Quality

<thinking> Quality criteria for skill instructions: 1. Are instructions clear and specific? 2. Are examples provided for complex concepts? 3. Is proper emphasis used (bold, code blocks, sections)? 4. Do structured thinking blocks guide reasoning? 5. Is the tone constructive and actionable? </thinking>

Clarity:

• [ ] Instructions are specific, not vague
• [ ] Technical terms are defined or demonstrated
• [ ] Expected behavior is clearly stated
• [ ] Step-by-step procedures where appropriate

Examples:

• [ ] Code examples for patterns to follow
• [ ] Sample outputs showing expected format
• [ ] Anti-patterns demonstrated (what NOT to do)
• [ ] File structure examples where relevant

Emphasis:

• [ ] Bold for critical requirements
• [ ] Code blocks for technical terms and examples
• [ ] Headers organize content logically
• [ ] Lists break down complex information

Structured Thinking:

• [ ] <thinking> blocks guide systematic analysis
• [ ] Key questions posed before each major step
• [ ] Decision criteria made explicit
• [ ] Reasoning process modeled for complex decisions

Constructive Tone:

• [ ] Focus on "do this" not just "don't do that"
• [ ] Explain rationale (why things matter)
• [ ] Provide actionable fixes, not just problem identification
• [ ] Avoid blame or judgment language

---

Fifth Pass: Token Efficiency

<thinking> Token efficiency considerations: 1. Is information organized for on-demand loading? 2. Are redundancies eliminated? 3. Is verbose language minimized without losing clarity? 4. Are examples concise but sufficient? </thinking>

Efficient Organization:

• [ ] Progressive disclosure implemented (load only what's needed)
• [ ] No duplicate information across files
• [ ] Reference other docs instead of copying content
• [ ] Clear routing to minimize unnecessary context loading

Concise Language:

• [ ] Direct statements preferred over verbose explanations
• [ ] Technical precision without fluff
• [ ] Examples are minimal but sufficient
• [ ] Headers and structure reduce need for transitional text

Avoid:

• Repeating same information in multiple places
• Loading all context upfront "just in case"
• Verbose explanations when examples suffice
• Including information not directly relevant to task

---

Priority Classification

Classify findings using reference/priority-framework.md:

• CRITICAL - Prevents functionality or exposes security vulnerabilities
• IMPORTANT - Significantly impacts quality or maintainability
• SUGGESTED - Improvements that aren't essential
• OPTIONAL - Personal preferences

---

Common Skill Anti-Patterns

Monolithic Skills:

• Single file > 500 lines
• All context loaded upfront
• No progressive disclosure strategy
• Fix: Split into main orchestration + supporting files

Vague Activation:

• Description: "Helps with code stuff"
• Better: "Reviews Kotlin code for MVVM violations. Use when checking ViewModels, state management, or UI layer architecture."

Missing Structured Thinking:

• Instructions without guidance on reasoning process
• No decision criteria for complex choices
• Fix: Add <thinking> blocks with key questions

Broken Progressive Disclosure:

• Supporting files reference each other circularly
• Files not self-contained
• Unclear when to load what
• Fix: Clear routing logic, self-contained files

Token Waste:

• Duplicate information across files
• Loading all context upfront
• Verbose explanations without adding value
• Fix: Reference instead of duplicate, load on-demand

---

Final Checklist Summary

Before completing review, verify:

• [ ] YAML frontmatter present and valid
• [ ] Main skill.md ≤ 500 lines
• [ ] No security issues (secrets, credentials)
• [ ] All file references valid
• [ ] Progressive disclosure properly implemented
• [ ] Structured thinking blocks present
• [ ] Clear activation triggers in description
• [ ] Examples provided for complex concepts
• [ ] Token-efficient organization
• [ ] Constructive, actionable feedback tone

Example Agent Configuration Reviews

Examples of agent configuration reviews showing common issues and best practices.

---

Example 1: Security Issues and Over-Privileged Access

Context: Reviewing a new documentation-writer agent with security concerns.

Agent Configuration

File: .claude/agents/documentation-writer.md

---
name: documentation-writer
description: Helps write documentation.
---
Write good documentation for code.

Review Comments

`.claude/agents/documentation-writer.md:3` - IMPORTANT: Description lacks activation triggers

Current description is too vague and doesn't specify when to use this agent.

Recommended:

description: Generates API documentation and code comments for TypeScript projects. Use when documenting functions, classes, or REST endpoints in .ts files.

Specific activation triggers improve automatic delegation and discoverability.

Reference: Anthropic Subagent Documentation - Description Best Practices

---

`.claude/agents/documentation-writer.md:1-6` - CRITICAL: Missing tools field - inherits all tools including Bash

Agent has no tools field, meaning it inherits ALL tools including destructive operations.

Recommended:

---
name: documentation-writer
description: Generates API documentation and code comments for TypeScript projects. Use when documenting functions, classes, or REST endpoints in .ts files.
tools: Read, Grep, Glob, Write
---

Rationale:

• Read/Grep/Glob: Analyze code to document
• Write: Create documentation files
• NO Edit: Doesn't modify source code
• NO Bash: Documentation doesn't require command execution

Security principle: Grant minimum necessary tools only.

Reference: reference/claude-code-requirements.md - Tool Access Patterns (lines 89-133)

---

`.claude/agents/documentation-writer.md:6` - IMPORTANT: System prompt lacks structure and guidance

Current prompt is too brief and unstructured.

Recommended:

# Documentation Writer Agent

## Role

You are a documentation specialist focused on creating clear, comprehensive API documentation for TypeScript projects.

## Process

<thinking>
Before documenting:
1. What is the function/class purpose?
2. What are the parameters and return types?
3. What are the edge cases or error conditions?
4. Are there usage examples needed?
</thinking>

## Output Format

Use JSDoc format:
\`\`\`typescript
/\*\*

- [Brief description]
-
- @param {Type} paramName - Parameter description
- @returns {Type} Return value description
- @throws {ErrorType} When error occurs
- @example
- // Usage example
  \*/
  \`\`\`

## Examples

[Include 2-3 examples of good documentation]

Structured thinking reduces errors by 40% (Anthropic Chain of Thought research).

---

`.claude/agents/documentation-writer.md:1-6` - SUGGESTED: Add model selection

Consider specifying model for cost/performance optimization:

---
name: documentation-writer
description: ...
tools: Read, Grep, Glob, Write
model: sonnet # Or haiku for simple documentation
---

Documentation generation is moderately complex (Sonnet) but could use Haiku for speed if following strict templates.

Reference: reference/claude-code-requirements.md - Model Selection (lines 73-86)

---

Summary

Overall Assessment: REQUEST CHANGES

This agent requires fixes before approval:

Must Fix (CRITICAL):

• Add tools field with minimum required access (prevent security risk)

Should Fix (IMPORTANT):

• Improve description with specific activation triggers
• Add structured system prompt with examples

Nice to Have (SUGGESTED):

• Specify model selection

Once security issues are addressed and description improved, this will be ready for use.

---

Example 2: Well-Configured Agent with Minor Suggestions

Context: Reviewing a production-ready security-scanner agent.

Agent Configuration

File: plugins/security-tools/agents/security-scanner.md

---
name: security-scanner
description: Analyzes code for security vulnerabilities including SQL injection, XSS, and authentication bypass. PROACTIVELY invoke when reviewing authentication, database queries, or user input handling.
tools: Read, Grep, Glob
model: sonnet
version: 1.0.0
---

# Security Scanner Agent

## Role
You are a security analysis specialist focused on identifying vulnerabilities in web applications.

## Capabilities
- SQL injection detection (parameterized queries, raw SQL)
- XSS vulnerability identification (unescaped output, DOM manipulation)
- Authentication bypass patterns (token validation, session handling)
- CSRF vulnerability detection
- Insecure cryptography usage
- Sensitive data exposure

## Process

<thinking>
Before analyzing each file:
1. What is the file's purpose (auth, API, database)?
2. What are the main security risks for this component?
3. Are there user inputs that need validation?
4. Are outputs properly escaped?
5. Is authentication/authorization properly implemented?
</thinking>

Then execute:
1. Read file and understand context
2. Identify all user input points
3. Trace data flow through functions
4. Check for security anti-patterns
5. Verify proper validation and sanitization
6. Document findings with severity and fix recommendations

## Output Format

**file.py:42** - CRITICAL: [Vulnerability type]

[Specific fix with secure code example]

[Rationale explaining security impact and OWASP category]

## Examples

### Example 1: SQL Injection
**api/users.py:78** - CRITICAL: SQL injection vulnerability

Current code uses string concatenation for SQL query:
\`\`\`python
query = f"SELECT * FROM users WHERE id = {user_id}"
\`\`\`

Fix with parameterized query:
\`\`\`python
query = "SELECT * FROM users WHERE id = %s"
cursor.execute(query, (user_id,))
\`\`\`

Rationale: String concatenation allows SQL injection attacks. Parameterized queries prevent this by properly escaping inputs. (OWASP A03:2021 - Injection)

### Example 2: XSS Vulnerability
**templates/profile.html:23** - CRITICAL: Cross-site scripting (XSS)

Current code outputs user data without escaping:
\`\`\`html
<div>{{ user.bio }}</div>
\`\`\`

Fix with auto-escaping:
\`\`\`html
<div>{{ user.bio | escape }}</div>
\`\`\`

Rationale: Unescaped user input allows script injection. Template escaping prevents XSS attacks. (OWASP A03:2021 - Injection)

## Constraints
- Focus ONLY on security issues
- Do not report code style or general quality issues
- Prioritize by severity: CRITICAL > HIGH > MEDIUM > LOW
- Provide specific fix for each finding
- Reference OWASP category where applicable

Review Comments

`plugins/security-tools/agents/security-scanner.md:1-8` - OPTIONAL: Excellent configuration

This agent configuration demonstrates security best practices:

✅ Specific, descriptive name ✅ Clear description with activation triggers ("PROACTIVELY invoke when...") ✅ Minimal tool access (Read, Grep, Glob only - appropriate for analysis) ✅ Explicit model selection (Sonnet for balanced analysis) ✅ Comprehensive system prompt with examples ✅ Structured thinking guidance ✅ Clear output format specification ✅ Security-focused constraints

No changes required. This is a reference-quality agent configuration.

---

`plugins/security-tools/agents/security-scanner.md:15-25` - OPTIONAL: Consider additional capabilities

Current capabilities are comprehensive for web applications. For even broader coverage, consider adding:

• Container/Docker security misconfigurations
• API security (rate limiting, API key exposure)
• Dependency vulnerability scanning
• Security header validation

However, keeping focused scope (current approach) may be preferable for clarity and single responsibility principle.

This is a design choice - current scope is excellent.

---

Summary

Overall Assessment: APPROVE

This is an exemplary agent configuration that demonstrates:

• Security best practices (minimal tool access)
• Clear activation triggers for automatic delegation
• Comprehensive system prompt with structured thinking
• Concrete examples demonstrating expected output
• Appropriate model selection
• Focused single responsibility

No changes required. Consider this a reference implementation for security analysis agents.

---

Example 3: Agent with Wrong Model Selection

Context: Reviewing a code formatter agent.

Agent Configuration

File: .claude/agents/code-formatter.md

---
name: code-formatter
description: Formats code according to project style guides.
tools: Read, Write, Edit
model: opus
---
Format code files using project style guide.

Review Comments

`.claude/agents/code-formatter.md:5` - IMPORTANT: Model selection inappropriate for task

Current configuration uses opus for code formatting, which is expensive overkill.

Recommended:

model: haiku # Fast and cost-effective for mechanical tasks

Rationale:

• Code formatting is mechanical, doesn't require complex reasoning
• Haiku is 10x+ faster and significantly cheaper
• Opus should be reserved for complex architectural decisions
• This agent will be invoked frequently (cost multiplier)

Reference: reference/claude-code-requirements.md - Model Selection (lines 73-86)

---

`.claude/agents/code-formatter.md:4` - IMPORTANT: Tool access includes unnecessary Edit

Code formatter likely creates formatted versions, doesn't need Edit for in-place modification.

Recommended:

tools: Read, Write # Remove Edit

Or if in-place formatting is required:

tools: Read, Edit # Remove Write

Clarify in system prompt whether agent:

• Reads and writes new formatted files (Read, Write)
• Modifies files in place (Read, Edit)

Reference: reference/claude-code-requirements.md - Tool Access Patterns (lines 89-133)

---

`.claude/agents/code-formatter.md:7` - IMPORTANT: System prompt lacks specification

Current prompt doesn't specify:

• Which style guide to use
• What file types to format
• Output format expectations

Recommended:

# Code Formatter Agent

## Role

Format code files according to project style guides automatically.

## Supported Languages

- Python: Black formatter (PEP 8)
- TypeScript: Prettier (project .prettierrc)
- Go: gofmt

## Process

1. Read file and detect language
2. Apply appropriate formatter rules
3. Write formatted output
4. Report files formatted and any errors

## Output

- List of files successfully formatted
- Any files skipped (unsupported language, errors)
- Summary of changes made

Clear specification prevents ambiguous behavior.

---

Summary

Overall Assessment: REQUEST CHANGES

Must Fix (IMPORTANT):

• Change model from opus to haiku (cost/performance)
• Clarify tool access (Write OR Edit, not both)
• Add comprehensive system prompt

Formatting is a high-frequency operation. Wrong model selection will significantly impact cost and latency at scale.

---

Example 4: Agent Invocation Review

Context: Reviewing a skill that invokes agents.

Skill Code

File: .claude/skills/code-reviewer/skill.md

## Step 3: Invoke Reviewer

Use the code-reviewer agent.

Review Comments

`.claude/skills/code-reviewer/skill.md:28` - IMPORTANT: Agent invocation lacks specificity

Current invocation is too vague and provides no context or expectations.

Recommended:

## Step 3: Invoke Security Analysis

Invoke the security-scanner agent to analyze modified files for vulnerabilities:

**Files to analyze:**
{list of modified files from step 1}

**Focus areas:**

- Authentication and authorization logic
- Database query construction
- User input handling and validation
- Output encoding and XSS prevention

**Expected output:**

- Inline comments with file:line references
- CRITICAL priority for vulnerabilities
- Specific fix recommendations with secure code examples
- OWASP category for each finding

**Context:**

- Application uses JWT authentication
- Database is PostgreSQL with SQLAlchemy ORM
- Framework is Flask with Jinja2 templates

Specific invocations with context improve agent output quality by ~40%.

---

Example 5: Circular Agent Dependency (Anti-Pattern)

Context: Reviewing agents that invoke each other circularly.

Configuration

Agent A: .claude/agents/code-analyzer.md

If issues found, invoke code-fixer agent.

Agent B: .claude/agents/code-fixer.md

After fixing, invoke code-analyzer agent to verify.

Review Comments

`.claude/agents/code-analyzer.md:45` + `.claude/agents/code-fixer.md:38` - CRITICAL: Circular agent dependency

These agents invoke each other, creating a potential infinite loop:

• code-analyzer → code-fixer → code-analyzer → ...

Fix:

# code-analyzer.md

Report issues found. Do NOT invoke other agents.

# code-fixer.md

After fixing, report completion. Do NOT invoke analyzer.

# Create separate coordinator if needed:

# code-improvement-workflow.md

1. Invoke code-analyzer
2. Review results
3. If fixes needed, invoke code-fixer
4. Verify results manually or with single analyzer invocation

Rationale: Circular dependencies cause unpredictable behavior and infinite loops. Use explicit workflow coordination instead.

---

Key Takeaways

Excellent Agent Patterns

1. Minimal tool access - Grant only necessary tools 2. Specific descriptions - Include activation triggers 3. Structured system prompts - Use thinking blocks and examples 4. Appropriate model - Match complexity to cost/performance 5. Clear constraints - Define what agent doesn't do

Common Mistakes

1. Over-privileged - Inheriting all tools unnecessarily 2. Vague descriptions - No activation triggers 3. Wrong model - Opus for simple tasks, Haiku for complex 4. Poor prompts - No structure, examples, or guidance 5. Scope creep - Trying to do too many things

Security Priorities

1. Always specify tools unless all tools genuinely needed 2. Justify Bash access explicitly in system prompt 3. Read-only for analysis agents 4. Document security implications of tool choices

---

Example CLAUDE.md Review

Context: Reviewing CLAUDE.md that duplicates architecture documentation.

Review Comments

`.claude/CLAUDE.md:50-250` - IMPORTANT: Duplicates docs/ARCHITECTURE.md content

This section copies 200 lines of MVVM patterns, Hilt DI setup, and module organization from docs/ARCHITECTURE.md.

Replace with reference:

## Core Directives

1. **Adhere to Architecture**: All code MUST follow patterns in `docs/ARCHITECTURE.md`
2. **Follow Code Style**: ALWAYS follow `docs/STYLE_AND_BEST_PRACTICES.md`
3. **Error Handling**: Use Result types and sealed classes per architecture guidelines

## Reference Documentation

Critical resources:

- `docs/ARCHITECTURE.md` - Architecture patterns and principles
- `docs/STYLE_AND_BEST_PRACTICES.md` - Code style guidelines

**Do not duplicate information from these files - reference them instead.**

Rationale: CLAUDE.md should provide high-level directives and references, not duplicate detailed specs. This:

• Reduces token usage (200 lines → 10 lines)
• Prevents documentation drift (single source of truth)
• Improves maintainability

Reference: Progressive disclosure, DRY principle

---

`.claude/CLAUDE.md:300` - SUGGESTED: Add decision-making guidance

Consider adding clear guidance on when to ask vs proceed autonomously:

## Decision-Making

Defer to user for high-impact decisions:

- Architecture/module changes
- Public API modifications
- Security mechanism changes

Proceed autonomously for:

- Implementation details within established patterns
- Test additions
- Bug fixes following existing patterns

This helps Claude make appropriate judgment calls without over-asking or under-asking.

---

Summary Comment

Overall Assessment: REQUEST CHANGES

Must Fix (IMPORTANT):

• Remove duplicated architecture content, replace with references

This reduces token usage by ~80% while improving maintainability. The rest of the file is well-structured.

---

Example Prompts Review

Context: Reviewing a new slash command prompt.

Review Comments

`.claude/commands/review-feature.md:1` - IMPORTANT: Missing usage information

Add usage format and example after description:

# review-feature

Reviews a feature implementation for architectural compliance and code quality.

**Usage:** /review-feature <feature-name>

**Example:** /review-feature user-authentication

This command analyzes all files related to the specified feature.

Users need clear invocation syntax. Without it, they may guess incorrectly or not use the command at all.

---

`.claude/commands/review-feature.md:10` - IMPORTANT: Vague instructions

Current: "Look at the code and check for issues."

Change to specific criteria:

Analyze feature implementation for:

1. **Architecture Compliance**
   - MVVM pattern adherence
   - Proper dependency injection
   - Module boundaries respected

2. **Code Quality**
   - Error handling (Result types)
   - Null safety
   - KDoc documentation on public APIs

3. **Testing**
   - Unit tests for business logic
   - UI tests for user flows
   - Edge cases covered

Specific criteria ensure consistent, thorough reviews.

Reference: Prompt engineering - Specificity

---

`.claude/commands/review-feature.md:25` - SUGGESTED: Add expected output format

Show reviewers what the output should look like:

````markdown Expected Output Format:

\```

Feature: [name]

Architecture: ✅ Pass / ❌ Issues Found

[Details]

Code Quality: ✅ Pass / ❌ Issues Found

[Details]

Testing: ✅ Pass / ❌ Issues Found

[Details] \`` ```

Explicit output format improves consistency and clarity.

---

`.claude/commands/review-feature.md:30` - SUGGESTED: Reference existing skill

If a reviewing-changes skill exists, consider referencing it:

## Implementation

Use the `reviewing-changes` skill with feature-addition checklist:

1. Identify all files in feature scope
2. Apply feature-addition review checklist
3. Document findings in structured format above

Reusing existing skills improves consistency and reduces duplication.

---

Summary Comment

Overall Assessment: REQUEST CHANGES

Must Fix (IMPORTANT):

• Add usage syntax and example
• Replace vague instructions with specific criteria

Nice to Have (SUGGESTED):

• Add expected output format example
• Reference existing reviewing-changes skill if applicable

The core concept is good - this command would be very useful once the instructions are clarified and the usage format is documented.

---

Anti-Patterns to Avoid

❌ One Large Summary Comment

DON'T DO THIS:

**Overall Review**

I found these issues:
1. Missing YAML frontmatter on line 1
2. File too long (line 1-650)
3. No structured thinking (line 45)
4. Missing examples (line 120)
...

Why this is bad:

• All feedback in one comment, no specific line references
• Harder to track what's been addressed
• Loses context for each issue
• Doesn't retain history if comment is edited

DO THIS INSTEAD: Create separate inline comment for EACH issue on the specific line.

---

❌ Blame Language

DON'T DO THIS:

**file.kt:50** - You clearly don't understand MVVM. This is completely wrong.

Why this is bad:

• Attacks person, not code
• Discourages learning
• Creates defensive responses
• Unprofessional tone

DO THIS INSTEAD:

**file.kt:50** - IMPORTANT: Exposes mutable state

ViewModels should expose StateFlow, not MutableStateFlow:

[code example]

This prevents external mutation, enforcing unidirectional data flow.

Reference: docs/ARCHITECTURE.md#mvvm-pattern

Focus on code, provide rationale, offer solution.

---

❌ Vague Feedback

DON'T DO THIS:

**file.kt:100** - This could be better.

Why this is bad:

• No actionable guidance
• Unclear what "better" means
• Author doesn't know what to change

DO THIS INSTEAD:

**file.kt:100** - SUGGESTED: Extract complex logic to separate function

Current function is 50 lines with nested conditions. Consider extracting validation logic:

[before/after code example]

Improves readability and testability.

Specific issue, concrete solution, clear rationale.

---

❌ Missing Priority

DON'T DO THIS:

**settings.json:5** - Overly broad permissions.

Why this is bad:

• Unclear if this blocks approval
• Author doesn't know urgency
• May skip critical security fix

DO THIS INSTEAD:

**settings.json:5** - CRITICAL: Overly broad permissions

[specific fix]

[security rationale]

This must be fixed before approval.

Clear priority, specific fix, explicit blocking status.

---

Example Settings Review

Context: Reviewing settings.json with multiple security concerns.

Review Comments

`.claude/settings.json:5` - CRITICAL: Overly broad file permissions

Current:

"autoApprovedTools": [
  "Read://*"
]

Change to project-scoped:

"autoApprovedTools": [
  "Read://Users/username/projects/myproject/**"
]

Read://* grants read access to entire filesystem including:

• ~/.ssh/ (SSH keys)
• ~/.aws/ (AWS credentials)
• /etc/ (system config)
• All user documents and personal files

Scope to project directory only per principle of least privilege.

Reference: Security best practices - Permission scoping

---

`.claude/settings.json:8` - CRITICAL: Dangerous command auto-approved

Current:

"Bash:rm -rf:*"

REMOVE THIS IMMEDIATELY

rm -rf performs recursive deletion without confirmation. Auto-approving this command creates risk of accidental data loss.

If file deletion is needed frequently, scope to specific safe directories:

"Bash:rm -rf /tmp/project-build-cache:*"

Or require manual approval for all rm commands.

Reference: Security best practices - Dangerous commands

---

`.claude/settings.json:12` - IMPORTANT: Permissions reference sensitive directory

Current:

"Read://Users/username/.ssh/**"

Remove access to .ssh directory containing private keys.

If SSH config reading is required (rare), scope to specific config file:

"Read://Users/username/.ssh/config"

Never grant blanket access to directories containing credentials.

---

Summary Comment

Overall Assessment: BLOCK - Critical Security Issues

CRITICAL issues must be fixed immediately:

• Overly broad Read://* permission
• Auto-approved rm -rf command
• Access to .ssh directory

These issues expose significant security risks:

• Potential data loss from dangerous commands
• Exposure of SSH private keys and credentials
• Access to sensitive system files

Cannot approve until all CRITICAL issues are resolved.

After fixes, re-review the scoped permissions to ensure they follow principle of least privilege.

---

Example Skill Review

Context: Reviewing a new skill with structural and quality issues.

Review Comments

`.claude/skills/my-new-skill/skill.md:1` - CRITICAL: Missing YAML frontmatter

Skills require YAML frontmatter to be discoverable by Claude Code:

---
name: my-new-skill
description: Clear description with activation triggers. Use when [specific scenario].
version: 1.0.0
---

Without frontmatter, the skill won't be recognized by Claude Code and will never be invoked.

Reference: Anthropic Skills Documentation - YAML Requirements

---

`.claude/skills/my-new-skill/skill.md:1-650` - IMPORTANT: File exceeds 500 line limit

Main skill file is 650 lines, exceeding Anthropic's 500-line progressive disclosure recommendation.

Suggested structure:

my-new-skill/
├── skill.md (≤500 lines - routing logic only)
├── checklists/
│   ├── type-a.md
│   └── type-b.md
└── reference/
    └── detailed-guidance.md

Move detailed checklists and reference material to supporting files, load on-demand.

Rationale: Improves token efficiency, reduces context loading, enables better organization.

Reference: Progressive disclosure best practices

---

`.claude/skills/my-new-skill/skill.md:45` - IMPORTANT: Missing structured thinking blocks

Add <thinking> blocks before major decision points:

### Step 1: Detect Type

<thinking>
Key questions to determine type:
1. What files were modified?
2. What does the title indicate?
3. What's the scope of changes?
</thinking>

Analyze the changeset...

Research shows structured thinking reduces logic errors by 40% (Anthropic Chain of Thought study).

Reference: Anthropic Prompt Engineering - Structured Thinking

---

`.claude/skills/my-new-skill/skill.md:120` - SUGGESTED: Add concrete examples

This section describes the expected comment format but doesn't show an example. Consider adding:

````markdown Example inline comment:

\``` file.kt:123 - CRITICAL: Issue description

[Specific fix with code]

[Rationale] \`` ```

Examples improve clarity significantly, especially for complex output formats.

---

`.claude/skills/my-new-skill/skill.md:200` - OPTIONAL: Alternative phrasing

Current: "You should check for these patterns..."

Alternative: "Check for these patterns..."

More direct phrasing slightly improves token efficiency, but current version is perfectly functional.

---

Summary Comment

Overall Assessment: REQUEST CHANGES

This skill has strong potential but requires fixes before approval:

Must Fix (CRITICAL):

• Add YAML frontmatter (blocks recognition)

Should Fix (IMPORTANT):

• Reduce main file to ≤500 lines via progressive disclosure
• Add structured thinking blocks for key decisions

Nice to Have (SUGGESTED):

• Add concrete examples for output formats

Once the critical frontmatter is added and the file is restructured with progressive disclosure, this will be ready for approval. The core logic and approach are solid.

---

reviewing-claude-config

Comprehensive skill for reviewing Claude Code configuration files with security-first approach.

Overview

This skill provides systematic review guidance for Claude Code configuration files in .claude directories. It detects file types, applies appropriate review checklists, and enforces security best practices with executable detection scripts.

Use this skill when:

• Reviewing changes to CLAUDE.md files
• Reviewing skill files (skill.md and supporting files)
• Reviewing prompts or commands (.claude/prompts/*.md, .claude/commands/*.md)
• Reviewing settings files (.claude/settings.json)
• Validating Claude configuration security and quality

Features

Security-First Approach

• Detects committed settings.local.json files
• Scans for hardcoded secrets and credentials
• Validates permission scoping
• Identifies dangerous command auto-approvals
• Includes executable security-scan.sh script

Intelligent Routing

• Detects configuration file type automatically
• Routes to appropriate specialized checklist
• Progressive disclosure for token efficiency
• Structured thinking throughout review process

Quality Enforcement

• YAML frontmatter validation
• Progressive disclosure enforcement (500 line limit)
• Prompt engineering quality checks
• File reference integrity validation
• Token efficiency optimization

Comprehensive Coverage

• 4 specialized checklists: Skills, CLAUDE.md, Prompts, Settings
• 3 reference guides: Priority framework, security patterns, quality criteria
• 4 review examples: Demonstrating proper feedback format
• Executable security script: Automated security scanning

Installation

Option 1: Copy to Your Project

# Copy the entire skill directory to your project's .claude/skills/ directory
cp -r reviewing-claude-config /path/to/your/project/.claude/skills/

Option 2: Clone from Repository

# In your project's .claude/skills/ directory
cd .claude/skills/
git clone [repository-url] reviewing-claude-config

Verify Installation

# Check that skill is recognized by Claude Code
ls -la .claude/skills/reviewing-claude-config/SKILL.md

# Optionally, make security script executable
chmod +x .claude/skills/reviewing-claude-config/scripts/security-scan.sh

Usage

As a Skill (Recommended)

Claude Code will automatically invoke this skill when appropriate based on the description. You can also invoke it explicitly:

Review the changes to .claude/CLAUDE.md

The skill will:

1. Detect the file type (CLAUDE.md in this case) 2. Execute security scan 3. Load the appropriate checklist 4. Provide structured review with inline comments

Manual Security Scan

Run the executable security script directly:

# From the scripts directory
cd .claude/skills/reviewing-claude-config/scripts
./security-scan.sh

# Or scan a specific directory
./security-scan.sh /path/to/.claude

The script checks for:

• Committed settings.local.json
• Hardcoded secrets (API keys, tokens, passwords)
• Overly broad permissions
• Dangerous command auto-approvals

Examples

Review a new skill:

Review .claude/skills/my-new-skill/skill.md

Review settings changes:

Review the changes to .claude/settings.json

Review CLAUDE.md updates:

Review .claude/CLAUDE.md for quality and security

File Structure

reviewing-claude-config/
├── skill.md                          # Main orchestration file
├── checklists/                       # Specialized review checklists
│   ├── skills.md                     # Skill review checklist
│   ├── claude-md.md                  # CLAUDE.md review checklist
│   ├── prompts.md                    # Prompts/commands checklist
│   └── settings.md                   # Settings security checklist
├── reference/                        # Reference materials (loaded on-demand)
│   ├── priority-framework.md         # Issue classification system
│   ├── security-patterns.md          # Security checks and remediation
│   ├── prompt-engineering-quality.md # Quality criteria index (modular)
│   ├── quality-clarity.md            # Clarity criteria
│   ├── quality-specificity.md        # Specificity criteria
│   ├── quality-examples.md           # Examples criteria
│   ├── quality-emphasis.md           # Emphasis criteria
│   ├── quality-structure.md          # Structure criteria
│   ├── quality-context.md            # Context criteria
│   ├── quality-actionability.md      # Actionability criteria
│   ├── quality-structured-thinking.md # Structured thinking criteria
│   ├── quality-checklist.md          # Comprehensive quality checklist
│   └── quality-improvement-patterns.md # Common improvement patterns
├── examples/                         # Sample review outputs
│   ├── README.md                     # Examples index and loading guide
│   ├── example-skill-review.md       # Skill review example
│   ├── example-claude-md-review.md   # CLAUDE.md review example
│   ├── example-settings-review.md    # Settings review example
│   └── example-prompts-review.md     # Prompts review example
├── scripts/                          # Executable automation
│   └── security-scan.sh              # Comprehensive security scanner
├── docs/                             # Historical documentation
│   ├── CHANGELOG.md                  # Version history
│   ├── IMPLEMENTATION_PLAN.md        # Original implementation plan
│   └── FINAL_REPORT.md               # Implementation completion report
├── README.md                         # This file
└── LICENSE                           # MIT License

Review Process

The skill follows a systematic 5-step review process:

1. Detect File Type: Determines whether reviewing skills, CLAUDE.md, prompts, or settings 2. Execute Security Scan: Always performs critical security checks first 3. Load Appropriate Checklist: Routes to specialized review guidance 4. Consult References: Loads detailed criteria only when needed 5. Document Findings: Provides inline comments with specific fixes

Security Checks (Always First)

Regardless of file type, these checks are performed:

• ✅ settings.local.json NOT in git
• ✅ No hardcoded credentials
• ✅ Permissions appropriately scoped
• ✅ No dangerous command auto-approvals

If any security check fails, it's flagged as CRITICAL immediately.

Priority Levels

Issues are classified into four priority levels:

• CRITICAL: Prevents functionality, exposes security vulnerabilities (must fix)
• IMPORTANT: Significantly impacts quality or maintainability (should fix)
• SUGGESTED: Nice-to-have improvements (optional)
• OPTIONAL: Personal preferences (author decides)

Requirements

• Claude Code (tested with latest version)
• Git (for committed file detection in security scan)
• Bash (for security-scan.sh script)

Configuration

This skill works out-of-the-box with no configuration needed. It's 100% generic and supports any project type or language.

Customization

If you want to customize for your organization:

1. Modify checklists: Add project-specific requirements to checklist files 2. Adjust security patterns: Add organization-specific secret patterns to security-scan.sh 3. Update priority framework: Adjust severity levels based on team standards

Note: Keep changes generic to maintain portability if sharing with other teams.

Examples

This skill includes 5 comprehensive review examples demonstrating proper feedback format:

• examples/example-agent-review.md - Agent review with security and quality issues
• examples/example-skill-review.md - Skill review with multiple issues
• examples/example-claude-md-review.md - CLAUDE.md review with duplication
• examples/example-settings-review.md - Settings review with security concerns
• examples/example-prompts-review.md - Prompts review with quality improvements

Review Output Format

Each review follows this structure:

Inline Comments:

**file:line** - PRIORITY: Issue description

[Specific fix with code example]

[Rationale explaining why this matters]

Summary Comment:

**Overall Assessment:** APPROVE / REQUEST CHANGES

[Findings grouped by priority: CRITICAL → IMPORTANT → SUGGESTED → OPTIONAL]

Priority Levels

• CRITICAL - Prevents functionality, security vulnerabilities (must fix)
• IMPORTANT - Significant quality/maintainability impact (should fix)
• SUGGESTED - Nice-to-have improvements (could fix)
• OPTIONAL - Personal preferences, alternatives (consider)

Best Practices

Feedback Quality:

• Provide specific fixes with code examples, not just problem identification
• Explain rationale (the "why"), not just the "what"
• Include references to documentation when applicable
• Use precise file:line references

Tone:

• Constructive and specific, never dismissive
• Focus on code/config, not people
• Acknowledge complexity and trade-offs
• Balance criticism with recognition of what works well

Research Foundation

This skill incorporates research-backed best practices:

• Chain of Thought prompting: 40% error reduction (Anthropic)
• Progressive disclosure: <500 line main files (Anthropic)
• Structured thinking: Systematic analysis before feedback
• Security-first approach: Critical checks before quality review

See docs/IMPLEMENTATION_PLAN.md for detailed research sources.

Troubleshooting

Skill Not Recognized

Issue: Claude doesn't invoke the skill automatically

Solutions:

1. Verify YAML frontmatter exists in skill.md 2. Check skill name is reviewing-claude-config 3. Ensure file is in .claude/skills/reviewing-claude-config/ 4. Try invoking explicitly: "Use reviewing-claude-config skill"

Security Script Fails

Issue: ./security-scan.sh returns errors

Solutions:

1. Make executable: chmod +x security-scan.sh 2. Verify you're in a git repository (for git commands) 3. Check script has access to .claude directory 4. Review error messages for specific issues

False Positives in Security Scan

Issue: Security scan detects patterns in documentation

Solutions:

1. Security scan excludes examples/ and security-patterns.md 2. Use "example" or "your-key-here" as placeholders in docs 3. Review manually to confirm false positives

Contributing

This skill is designed for internal team use but follows open-source best practices.

To contribute improvements:

1. Test changes in your project first 2. Ensure changes remain 100% generic (no project-specific references) 3. Update CHANGELOG.md with changes 4. Increment version in skill.md YAML frontmatter (semver)

Versioning

This skill follows Semantic Versioning:

• MAJOR: Breaking changes to skill interface or file structure
• MINOR: New features, new checklists, backward-compatible changes
• PATCH: Bug fixes, documentation updates, minor improvements

Current version: 1.0.0

See CHANGELOG.md for version history.

Support

For issues, questions, or feedback:

1. Check troubleshooting section above 2. Review examples in examples/review-outputs.md 3. Consult reference files for detailed guidance 4. Contact your team's Claude Code administrator

Acknowledgments

Built with research-backed best practices from:

• Anthropic Official Documentation (Chain of Thought, Progressive Disclosure)
• Claude Code Best Practices
• Security best practices for credential detection
• Prompt engineering quality standards

Claude Code Requirements

Claude Code-specific conventions, formats, and requirements that differ from general best practices. This reference consolidates domain-specific knowledge necessary for validating Claude Code configuration files.

---

YAML Frontmatter Format

Skills (SKILL.md files)

Required Fields:

---
name: skill-name-in-kebab-case
description: Clear description with activation triggers
---

Optional Fields:

version: 1.0.0 # Semver format (MAJOR.MINOR.PATCH)

Field Requirements:

• name: MUST be kebab-case (use-dashes-not_underscores)
• description: MUST include activation triggers (when to use the skill)
• version: SHOULD follow semantic versioning if marketplace-bound
• NO TABS: Use spaces only (YAML requirement)

Valid Example:

---
name: reviewing-changes
version: 2.0.0
description: Comprehensive code reviews for Android. Detects change type and applies appropriate review depth. Use when reviewing pull requests, checking commits, or analyzing code changes.
---

Invalid Examples:

---
name: reviewing_changes # ❌ Underscore instead of dash
description: Reviews code # ❌ Too vague, no activation triggers
---

---

Agents (.claude/agents/_.md or plugins/_/agents/\*.md)

Required Fields:

---
name: agent-name-in-kebab-case
description: Clear description of agent purpose
---

Optional Fields:

model: sonnet # haiku, sonnet, opus, or inherit
tools: Read, Write, Grep, Glob, Bash # Specific tools only

Field Requirements:

• name: kebab-case, unique within project
• description: Clear purpose and activation context
• model: One of: haiku, sonnet, opus, inherit (lowercase)
• tools: Exact tool names (case-sensitive): Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch
• Omit `tools` field to inherit all tools (default)

---

Model Selection

Valid Model Values

Default: If model field omitted, defaults to sonnet

---

Tool Access Patterns

Tool Names (Case-Sensitive)

Read-Only Tools (LOW RISK):

• Read - Read file contents
• Grep - Search file contents
• Glob - Find files by pattern

Write Tools (MEDIUM RISK):

• Write - Create new files
• Edit - Modify existing files

Execution Tools (HIGH RISK):

• Bash - Execute shell commands

Network Tools (MEDIUM-HIGH RISK):

• WebFetch - Fetch URL content
• WebSearch - Search web

Tool Access Security

Read-only agents (safest pattern):

tools: Read, Grep, Glob

Write-capable agents (moderate risk):

tools: Read, Grep, Glob, Write, Edit

Full-access agents (highest risk - justify in review):

# Omit tools field to inherit all tools
# OR explicitly list all needed tools

Tool Security Guidelines

1. Principle of Least Privilege: Only grant tools agent actually needs 2. Read-Only by Default: Start with Read, Grep, Glob and add tools as needed 3. Justify Bash Access: Bash tool = arbitrary code execution, requires strong justification 4. Omit for Full Access: Omitting tools field grants all tools (document why this is necessary)

---

Progressive Disclosure

500-Line Guideline

Main skill file (SKILL.md):

• Target: ≤500 lines
• Maximum: 500 lines is guideline, not hard limit
• Rationale: Context window efficiency, cognitive load management

If exceeding 500 lines:

• Split into supporting files
• Use on-demand loading pattern
• Organize into subdirectories

File Organization Pattern

skill-name/
├── SKILL.md              # Main orchestration (aim for ≤500 lines)
├── checklists/           # Task-specific procedures
├── reference/            # Detailed criteria (loaded as needed)
├── examples/             # Sample outputs
└── scripts/              # Executable automation (if applicable)

On-Demand Loading

Main file should:

• Provide routing logic (which file to load when)
• Reference supporting files explicitly
• Use structured thinking to guide decisions

Supporting files should:

• Be self-contained (understandable in isolation)
• State clear purpose at top
• Avoid circular dependencies

Example routing:

### Step 2: Load Appropriate Checklist

Based on detected type, read the relevant checklist:

- **Agents** → `checklists/agents.md`
- **Skills** → `checklists/skills.md`
- **Settings** → `checklists/settings.md`

---

Security Conventions

settings.local.json

CRITICAL: settings.local.json must NEVER be committed to git

Detection:

git status | grep "settings.local.json"
git diff --cached | grep "settings.local.json"

If found: Flag as CRITICAL blocking issue

Rationale: Contains user-specific settings and potentially sensitive paths

---

Auto-Approved Tool Patterns

Format (in settings.json):

{
  "autoApproved": [
    "Bash(git status:*)",
    "Bash(git diff:*)",
    "Read(/absolute/path/to/specific/dir/**)"
  ]
}

Guidelines:

• Use specific command patterns, not wildcards: Bash(git status:*) not Bash(*)
• Use absolute paths for Read permissions: Read(/full/path/**) not Read(**)
• Glob patterns for restricted access: Read(/project/src/**/*.ts) to limit file types

---

Common Validation Issues

YAML Errors

Tool Access Errors

Progressive Disclosure Violations

---

Validation Checklist

YAML Frontmatter:

• [ ] name field present and kebab-case
• [ ] description field present with activation triggers
• [ ] version follows semver (if present)
• [ ] model is valid value: haiku/sonnet/opus/inherit (if present)
• [ ] tools uses exact case-sensitive names (if present)
• [ ] No tabs (spaces only)
• [ ] Valid YAML syntax

Progressive Disclosure:

• [ ] Main SKILL.md file ≤500 lines
• [ ] Supporting files organized in subdirectories
• [ ] On-demand loading pattern used
• [ ] File references are correct and exist

Security:

• [ ] No settings.local.json committed
• [ ] No hardcoded credentials or API keys
• [ ] Tool access follows least privilege principle
• [ ] Bash access justified if granted

File Organization:

• [ ] Skills: SKILL.md with YAML frontmatter
• [ ] Agents: .claude/agents/*.md or plugins/*/agents/*.md
• [ ] Prompts: .claude/prompts/*.md or .claude/commands/*.md
• [ ] Settings: .claude/settings.json (NOT settings.local.json)

---

Quick Reference

Model Values: haiku | sonnet | opus | inherit

Tool Names: Read | Write | Edit | Grep | Glob | Bash | WebFetch | WebSearch

Line Limit: SKILL.md ≤500 lines (guideline)

Naming: kebab-case for name fields

NEVER Commit: settings.local.json

YAML: Spaces only, no tabs

Priority Framework for Claude Configuration Reviews

Classification system for prioritizing issues found in Claude configuration files.

---

Priority Levels

CRITICAL

Definition: Issues that prevent functionality, expose security vulnerabilities, or cause immediate harm.

Examples:

• settings.local.json committed to git
• Hardcoded API keys, tokens, or passwords
• Missing YAML frontmatter (skill won't be recognized)
• Dangerous command auto-approvals (rm -rf, chmod 777)
• Overly broad permissions exposing sensitive paths
• Broken file references preventing skill loading

Action Required: Must fix immediately before approval.

Review Comment Format:

**CRITICAL**: [Issue description]

[Specific fix with code example]

This must be fixed before approval because [security/functionality reason].

---

IMPORTANT

Definition: Issues that significantly impact quality, maintainability, or user experience but don't prevent basic functionality.

Examples:

• Duplicated documentation content
• Poor progressive disclosure (file > 500 lines)
• Missing structured thinking blocks
• Vague activation triggers
• Unclear purpose statements
• Inefficient token usage patterns
• Missing examples for complex concepts

Action Required: Should fix in this PR/commit. If time-constrained, create follow-up issue.

Review Comment Format:

**IMPORTANT**: [Issue description]

[Specific recommendation]

[Rationale explaining why this matters]

---

SUGGESTED

Definition: Improvements that enhance quality but aren't essential for approval.

Examples:

• Additional examples for clarity
• Better file organization
• More specific guidance
• Enhanced documentation
• Alternative approaches
• Stylistic improvements

Action Required: Optional improvements. Consider for future work.

Review Comment Format:

**SUGGESTED**: [Improvement suggestion]

[What would be better and why]

This would improve [aspect] but isn't required for approval.

---

OPTIONAL

Definition: Personal preferences, alternative approaches, or minor stylistic choices.

Examples:

• Alternative phrasing
• Different organizational structure
• Stylistic preferences
• Personal coding style

Action Required: Author decides. No expectation to change.

Review Comment Format:

**OPTIONAL**: [Observation or suggestion]

[Alternative approach if applicable]

This is a personal preference - feel free to keep current approach.

---

Classification Decision Tree

Use this structured thinking approach to classify issues:

<thinking> 1. Does this issue create security vulnerability or prevent functionality? → YES: CRITICAL → NO: Continue

2. Does this significantly impact quality, maintainability, or UX? → YES: IMPORTANT → NO: Continue

3. Would this improve quality but not essential? → YES: SUGGESTED → NO: OPTIONAL </thinking>

---

Context-Specific Priority Adjustments

Security Context

In security-sensitive configurations (settings.json, permissions):

• Elevate permission issues to CRITICAL
• Elevate secret exposure to CRITICAL
• Broad permissions: IMPORTANT → CRITICAL

Marketplace-Bound Skills

For skills intended for marketplace:

• Elevate missing examples to IMPORTANT
• Elevate unclear activation triggers to IMPORTANT
• Elevate poor progressive disclosure to CRITICAL

Internal Tools

For internal-only configurations:

• May accept some SUGGESTED issues
• Still require CRITICAL fixes
• IMPORTANT issues can be follow-up work

---

Priority by Issue Type

Security Issues

Structure Issues

Quality Issues

Syntax Issues

---

Multi-Issue Prioritization

When multiple issues exist in a single review:

1. Group by priority level (CRITICAL together, IMPORTANT together, etc.) 2. Within each level, order by:

• Security issues first
• Functionality issues second
• Quality issues third

3. Focus review comments on highest priorities 4. May skip OPTIONAL issues if many higher-priority issues exist

---

Communication Guidelines by Priority

CRITICAL

• Tone: Direct and firm
• Language: "Must fix", "Required", "Blocks approval"
• Explanation: Always explain the risk/impact
• Solution: Always provide specific fix

IMPORTANT

• Tone: Strong recommendation
• Language: "Should fix", "Recommended", "Significantly improves"
• Explanation: Explain why it matters
• Solution: Provide specific recommendation

SUGGESTED

• Tone: Helpful suggestion
• Language: "Consider", "Would improve", "Could enhance"
• Explanation: Brief rationale
• Solution: Optional, may suggest alternatives

OPTIONAL

• Tone: Neutral observation
• Language: "Alternative approach", "Personal preference"
• Explanation: Acknowledge it's not critical
• Solution: Present as option, not directive

---

Example Classifications

Example 1: Security Issue

❌ settings.json:5 - settings.local.json committed to git Priority: CRITICAL Rationale: Exposes potentially sensitive user-specific configuration and API keys.

---

Example 2: Structure Issue

❌ skill.md:1 - Missing YAML frontmatter Priority: CRITICAL Rationale: Skill won't be recognized by Claude Code without frontmatter.

---

Example 3: Quality Issue

❌ skill.md:3 - Description lacks activation triggers Priority: IMPORTANT Rationale: Users won't know when to invoke this skill. Reduces discoverability.

---

Example 4: Improvement Suggestion

❌ checklist.md:45 - Could add more examples Priority: SUGGESTED Rationale: Additional examples would clarify complex concept, but current instruction is functional.

---

Example 5: Style Preference

❌ skill.md:12 - Alternative phrasing possible Priority: OPTIONAL Rationale: Current phrasing is clear, alternative is just personal preference.

Security Patterns for Claude Configuration

Security checks, detection commands, and remediation patterns for Claude configuration files.

---

Critical Security Checks

Perform these checks for EVERY Claude configuration review:

1. settings.local.json NOT in git 2. No hardcoded credentials 3. Permissions appropriately scoped 4. No dangerous command auto-approvals

If ANY check fails, flag as CRITICAL immediately.

---

Detection Scripts

Check 1: Detect Committed settings.local.json

Manual Detection:

# Check if file is tracked by git
git ls-files | grep "settings.local.json"

# If output exists, file is incorrectly committed

Expected Output:

• Empty: File not tracked (GOOD)
• File path: File is tracked (CRITICAL)

Automated Detection:

#!/bin/bash
# detect-committed-local-settings.sh

if git ls-files | grep -q "settings.local.json"; then
    echo "CRITICAL: settings.local.json is committed to git"
    exit 1
else
    echo "OK: settings.local.json not in git"
    exit 0
fi

---

Check 2: Scan for Hardcoded Secrets

Pattern Detection:

# Search for common secret patterns
grep -rE "(apiKey|api_key|API_KEY|password|passwd|token|secret)\s*[:=]\s*['\"]" .claude/

# Search for specific key prefixes
grep -rE "(sk-[a-zA-Z0-9]{32,}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36})" .claude/

Common Secret Patterns:

Automated Detection:

#!/bin/bash
# detect-hardcoded-secrets.sh

FOUND_SECRETS=0

# OpenAI keys
if grep -rE "sk-[a-zA-Z0-9]{32,}" .claude/ 2>/dev/null; then
    echo "CRITICAL: Found OpenAI API key pattern"
    FOUND_SECRETS=1
fi

# GitHub tokens
if grep -rE "gh[po]_[a-zA-Z0-9]{36}" .claude/ 2>/dev/null; then
    echo "CRITICAL: Found GitHub token pattern"
    FOUND_SECRETS=1
fi

# Generic API keys and passwords
if grep -rE "(apiKey|api_key|password|token)\s*[:=]\s*['\"][^'\"]{8,}" .claude/ 2>/dev/null; then
    echo "CRITICAL: Found potential hardcoded credential"
    FOUND_SECRETS=1
fi

if [ $FOUND_SECRETS -eq 0 ]; then
    echo "OK: No hardcoded secrets detected"
    exit 0
else
    exit 1
fi

---

Check 3: Validate Permission Scoping

Dangerous Permission Patterns:

# Check for overly broad permissions
grep -r "Read://\*" .claude/settings.json
grep -r "Write://\*" .claude/settings.json
grep -r "Bash:\*" .claude/settings.json

Red Flags:

• Read://* - Read access to entire filesystem
• Write://* - Write access to entire filesystem
• Bash:* - Auto-approve ALL bash commands
• Read://Users/username/.ssh/** - Access to SSH keys
• Read:///etc/** - Access to system config

Automated Detection:

#!/bin/bash
# detect-broad-permissions.sh

ISSUES=0

if grep -q 'Read://\*"' .claude/settings.json 2>/dev/null; then
    echo "CRITICAL: Overly broad Read permissions (Read://*)"
    ISSUES=1
fi

if grep -q 'Write://\*"' .claude/settings.json 2>/dev/null; then
    echo "CRITICAL: Overly broad Write permissions (Write://*)"
    ISSUES=1
fi

if grep -q '"Bash:\*"' .claude/settings.json 2>/dev/null; then
    echo "CRITICAL: Auto-approve all Bash commands (Bash:*)"
    ISSUES=1
fi

# Check for sensitive paths
if grep -rE '(\.ssh|/etc|\.aws|\.config)' .claude/settings.json 2>/dev/null; then
    echo "WARNING: Permissions reference sensitive directories"
    ISSUES=1
fi

if [ $ISSUES -eq 0 ]; then
    echo "OK: Permissions appropriately scoped"
    exit 0
else
    exit 1
fi

---

Check 4: Detect Dangerous Command Auto-Approvals

Dangerous Command Patterns:

# Check for dangerous commands
grep -E "(rm -rf|chmod 777|mkfs|dd|curl.*\| sh)" .claude/settings.json

Dangerous Commands List:

Automated Detection:

#!/bin/bash
# detect-dangerous-commands.sh

DANGEROUS_PATTERNS=(
    "rm -rf"
    "rm -fr"
    "git push --force"
    "git push -f"
    "chmod 777"
    "chmod 666"
    "curl.*| sh"
    "curl.*| bash"
    "wget.*| sh"
    "dd if="
    "mkfs"
    "> /dev/sd"
)

FOUND_DANGEROUS=0

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if grep -qE "$pattern" .claude/settings.json 2>/dev/null; then
        echo "CRITICAL: Dangerous command auto-approved: $pattern"
        FOUND_DANGEROUS=1
    fi
done

if [ $FOUND_DANGEROUS -eq 0 ]; then
    echo "OK: No dangerous command auto-approvals"
    exit 0
else
    exit 1
fi

---

Comprehensive Security Scan Script

Full automated security scan:

#!/bin/bash
# security-scan.sh
# Comprehensive security scan for Claude configuration files

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
CLAUDE_DIR="${SCRIPT_DIR}/.."
ISSUES_FOUND=0

echo "=== Claude Configuration Security Scan ==="
echo ""

# Check 1: Committed settings.local.json
echo "[1/4] Checking for committed settings.local.json..."
if git ls-files | grep -q "settings.local.json"; then
    echo "  ❌ CRITICAL: settings.local.json is committed to git"
    ISSUES_FOUND=$((ISSUES_FOUND + 1))
else
    echo "  ✅ OK: settings.local.json not in git"
fi
echo ""

# Check 2: Hardcoded secrets
echo "[2/4] Scanning for hardcoded secrets..."
SECRET_FOUND=0

if grep -rE "sk-[a-zA-Z0-9]{32,}" "${CLAUDE_DIR}" 2>/dev/null | grep -v "security-scan.sh"; then
    echo "  ❌ CRITICAL: OpenAI API key pattern detected"
    SECRET_FOUND=1
fi

if grep -rE "gh[po]_[a-zA-Z0-9]{36}" "${CLAUDE_DIR}" 2>/dev/null | grep -v "security-scan.sh"; then
    echo "  ❌ CRITICAL: GitHub token pattern detected"
    SECRET_FOUND=1
fi

if grep -rE '(apiKey|api_key|password|token)["'\'']?\s*[:=]\s*["'\''][^"'\'']{8,}' "${CLAUDE_DIR}" 2>/dev/null | grep -v "security-scan.sh" | grep -v "example"; then
    echo "  ❌ CRITICAL: Potential hardcoded credential detected"
    SECRET_FOUND=1
fi

if [ $SECRET_FOUND -eq 0 ]; then
    echo "  ✅ OK: No hardcoded secrets detected"
else
    ISSUES_FOUND=$((ISSUES_FOUND + 1))
fi
echo ""

# Check 3: Broad permissions
echo "[3/4] Validating permission scoping..."
PERM_ISSUES=0

if [ -f "${CLAUDE_DIR}/settings.json" ]; then
    if grep -q 'Read://\*' "${CLAUDE_DIR}/settings.json"; then
        echo "  ❌ CRITICAL: Overly broad Read permissions (Read://*)"
        PERM_ISSUES=1
    fi

    if grep -q 'Write://\*' "${CLAUDE_DIR}/settings.json"; then
        echo "  ❌ CRITICAL: Overly broad Write permissions (Write://*)"
        PERM_ISSUES=1
    fi

    if grep -q '"Bash:\*"' "${CLAUDE_DIR}/settings.json"; then
        echo "  ❌ CRITICAL: Auto-approve all Bash commands"
        PERM_ISSUES=1
    fi

    if grep -qE '(\.ssh|\.aws|\.gnupg)' "${CLAUDE_DIR}/settings.json"; then
        echo "  ⚠️ WARNING: Permissions reference sensitive directories"
        PERM_ISSUES=1
    fi

    if [ $PERM_ISSUES -eq 0 ]; then
        echo "  ✅ OK: Permissions appropriately scoped"
    else
        ISSUES_FOUND=$((ISSUES_FOUND + 1))
    fi
else
    echo "  ℹ️  No settings.json found (OK)"
fi
echo ""

# Check 4: Dangerous commands
echo "[4/4] Checking for dangerous command auto-approvals..."
DANGEROUS_FOUND=0

if [ -f "${CLAUDE_DIR}/settings.json" ]; then
    DANGEROUS_PATTERNS=(
        "rm -rf"
        "rm -fr"
        "git push --force"
        "git push -f"
        "chmod 777"
        "curl.*\| sh"
        "curl.*\| bash"
        "wget.*\| sh"
        "dd if="
        "mkfs"
    )

    for pattern in "${DANGEROUS_PATTERNS[@]}"; do
        if grep -qE "$pattern" "${CLAUDE_DIR}/settings.json"; then
            echo "  ❌ CRITICAL: Dangerous command auto-approved: ${pattern}"
            DANGEROUS_FOUND=1
        fi
    done

    if [ $DANGEROUS_FOUND -eq 0 ]; then
        echo "  ✅ OK: No dangerous command auto-approvals"
    else
        ISSUES_FOUND=$((ISSUES_FOUND + 1))
    fi
else
    echo "  ℹ️  No settings.json found (OK)"
fi
echo ""

# Summary
echo "=== Scan Complete ==="
if [ $ISSUES_FOUND -eq 0 ]; then
    echo "✅ All security checks passed"
    exit 0
else
    echo "❌ Found ${ISSUES_FOUND} critical security issue(s)"
    echo ""
    echo "Review the issues above and remediate before approval."
    exit 1
fi

---

Remediation Patterns

Fix 1: Remove Committed settings.local.json

# Remove from git but keep locally
git rm --cached .claude/settings.local.json

# Ensure .gitignore includes it
if ! grep -q "settings.local.json" .gitignore; then
    echo ".claude/settings.local.json" >> .gitignore
fi

# Commit the fix
git add .gitignore
git commit -m "Remove settings.local.json from git tracking"

Fix 2: Remove Hardcoded Secrets

Before:

{
  "apiKey": "sk-1234567890abcdef"
}

After:

{
  "apiKeyVar": "$OPENAI_API_KEY",
  "note": "Set API key: export OPENAI_API_KEY=your-key"
}

Or remove entirely and document:

# Configuration

Set required environment variables:

- `OPENAI_API_KEY` - Your OpenAI API key

Fix 3: Scope Down Permissions

Before:

{
  "autoApprovedTools": ["Read://*"]
}

After:

{
  "autoApprovedTools": [
    "Read://Users/username/projects/myproject/**",
    "Read://Users/username/.claude/projects/**"
  ]
}

Fix 4: Remove Dangerous Commands

Before:

{
  "autoApprovedTools": ["Bash:*"]
}

After:

{
  "autoApprovedTools": [
    "Bash:git status:*",
    "Bash:git log:*",
    "Bash:git diff:*",
    "Bash:npm install:*",
    "Bash:./gradlew test:*"
  ]
}

---

Safe Command Whitelist

Read-Only Commands (Generally Safe):

• git status, git log, git diff, git show
• ls, cat, head, tail, less
• grep, find, wc, sort
• npm list, ./gradlew tasks

Idempotent Commands (Safe):

• npm install, npm ci
• ./gradlew build, ./gradlew test
• git pull (on feature branches)
• mkdir -p (with scoped paths)

Commands Requiring Approval:

• Any rm command
• git push --force
• chmod, chown
• Piped curl/wget
• System-level commands