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:

Detect the file type (CLAUDE.md in this case)
Execute security scan
Load the appropriate checklist
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:

Detect File Type: Determines whether reviewing skills, CLAUDE.md, prompts, or settings
Execute Security Scan: Always performs critical security checks first
Load Appropriate Checklist: Routes to specialized review guidance
Consult References: Loads detailed criteria only when needed
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:

Modify checklists: Add project-specific requirements to checklist files
Adjust security patterns: Add organization-specific secret patterns to security-scan.sh
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:

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

Security Script Fails

Issue: ./security-scan.sh returns errors

Solutions:

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

False Positives in Security Scan

Issue: Security scan detects patterns in documentation

Solutions:

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

Contributing

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

To contribute improvements:

Test changes in your project first
Ensure changes remain 100% generic (no project-specific references)
Update CHANGELOG.md with changes
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:

Check troubleshooting section above
Review examples in examples/review-outputs.md
Consult reference files for detailed guidance
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