| name | claude-code-quality-checklists |
| description | Quality validation checklists for Claude Code configuration artifacts including agents, skills, patterns, and CLAUDE.md files with scoring rubrics |
| user-invocable | false |
Claude Code Quality Validation Checklists
Created: 2025-10-21
Source: PR #164 claude-code-expert (your-org/da-agent-hub)
Purpose: Systematic quality validation for Claude Code configuration artifacts
Status: Production guidance
Overview
These checklists ensure Claude Code configuration follows Anthropic best practices for agents, skills, patterns, and CLAUDE.md files. Use during creation, review, and optimization.
When to use:
- Creating new agents or skills
- Reviewing configuration changes in PRs
- Auditing existing Claude Code setup
- Optimizing AI effectiveness
Agent Quality Checklist (7 Points)
1. YAML Frontmatter Complete and Valid ✅
Why: Frontmatter enables Claude Code to discover and invoke agents correctly.
Example:
---
name: dbt-expert
description: dbt transformation specialist. Consult proactively for model optimization, testing strategies, and performance issues.
model: sonnet
color: blue
---
2. Single-Purpose Focus ✅
Why: Single-purpose agents are easier to invoke correctly and provide more focused expertise.
Anti-pattern: "General data expert" (too broad)
Good pattern: "dbt transformation specialist" (focused)
3. Detailed System Prompt with Examples ✅
Why: Detailed prompts improve agent response quality and consistency.
Sections to include:
- Role & Expertise
- Core Responsibilities
- Available Tools
- Example Consultations
- Quality Standards
4. Strategic Tool Restrictions ✅
Why: Limiting tools maintains focus and reduces security risk.
Example:
### ✅ Allowed Tools
- Read, Grep, Glob (analysis)
- WebFetch (documentation research)
### ❌ Restricted Tools
- Bash, Write (research-only agent)
5. Action-Oriented Description ✅
Why: Encourages Claude to delegate to specialists when appropriate.
Good: "Consult proactively for dbt optimization, testing, and performance issues"
Bad: "Helps with dbt" (passive, vague)
6. Quality Standards Documented ✅
Why: Ensures consistent, high-quality agent outputs.
Example:
## Quality Standards
**Every recommendation must include**:
- ✅ Analysis of current state
- ✅ Specific recommendations
- ✅ Implementation steps
- ✅ Validation approach
7. Integration with Agent Ecosystem ✅
Why: Agents work together effectively when integration is clear.
Skill Quality Checklist (5 Points)
1. Clear Workflow Steps ✅
Why: Step-by-step workflows ensure consistent execution.
Structure:
### 1. Step Name
**Execute**: [tools/commands to use]
**Output**: [expected result]
**Error handling**: [what to do if fails]
2. Error Handling and Rollback ✅
Why: Skills should handle failures gracefully and inform users.
Example:
## Error Handling
### Project Already Exists
**Check**: Directory exists
**Action**: Ask user to confirm overwrite or choose new name
### Git Branch Exists
**Check**: Branch exists
**Action**: Suggest alternative or checkout existing
3. Reusability Across Contexts ✅
Why: Skills should be reusable, not one-off scripts.
Use variables: {project_name}, {date}, {user_input}
4. Quality Standards and Validation ✅
Why: Skills should validate their own outputs.
Example:
## Quality Standards
**Every project setup must**:
- ✅ Create all 4 core files
- ✅ Use consistent naming
- ✅ Create valid git branch
- ✅ Verify all files created
5. User-Facing Documentation ✅
Why: Users need to know when and how to use skills.
CLAUDE.md Quality Checklist (6 Points)
1. Specific Instructions, Not Generic Advice ✅
Why: Specific instructions improve Claude's effectiveness.
Bad: "Write good code"
Good: "Use PEP 8 style guide. Run black . before committing."
2. Markdown Structure with Clear Headers ✅
Why: Well-structured documentation is easier to parse and reference.
3. Import Patterns for Modularity (if >500 lines) ✅
Why: Modular structure improves readability and maintainability.
Example:
## Git Workflow
See @.claude/rules/git-workflow-patterns.md
## Testing
See @.claude/skills/reference-knowledge/testing-patterns/SKILL.md
4. Progressive Disclosure ✅
Why: Claude should find key information quickly.
Structure:
- Quick Start / Most Important
- Core Workflows
- Reference Documentation
- Advanced Topics
5. Version Control and Team Sharing ✅
Why: Teams benefit from shared, versioned Claude Code configuration.
6. Regular Review and Updates ✅
Why: Outdated instructions reduce AI effectiveness.
Pattern Quality Checklist (5 Points)
1. Production-Validated Solution ✅
Why: Only proven patterns should be documented.
Validation notes:
**Validated**:
- Project A: Reduced query time 80% (2024-09-15)
- Project B: Eliminated incremental issues (2024-10-03)
**Confidence**: 0.95 (High)
2. Decision Criteria ("When to Use") ✅
Why: Helps decide when to apply the pattern.
Example:
## When to Use This Pattern
**Use when**:
- ✅ Incremental models with large datasets (>10M rows)
- ✅ Query runtime > 1 hour
- ✅ Source system supports incremental extraction
**Don't use when**:
- ❌ Small datasets (<1M rows)
- ❌ Full refresh is acceptably fast
- ❌ Source system lacks updated_at column
3. Real-World Examples ✅
Why: Examples make patterns immediately actionable.
4. Cross-References to Related Patterns ✅
Why: Patterns form a knowledge network.
Example:
## Related Patterns
- [dbt Testing Patterns](./dbt-testing-patterns.md)
- [Snowflake Optimization](./snowflake-optimization-patterns.md)
## Related Agents
- dbt-expert: Use this pattern for optimization consultations
- snowflake-expert: For warehouse-side performance tuning
5. Maintenance Information ✅
Why: Patterns evolve as technologies and practices change.
Metadata:
**Last Validated**: 2025-10-15
**Next Review**: 2026-01-15 (quarterly)
**Confidence**: 0.92
**Limitations**: Requires dbt 1.6+, Snowflake warehouse
Usage Guide
During Creation
New Agent:
- Create agent file from template
- Use Agent Quality Checklist (7 points)
- Ensure all ✅ checked before committing
New Skill:
- Document workflow steps clearly
- Use Skill Quality Checklist (5 points)
- Test with 3+ diverse scenarios
New Pattern:
- Validate in ≥2 projects first
- Use Pattern Quality Checklist (5 points)
- Add confidence score
During PR Review
Review Checklist:
- Identify which checklists apply
- Verify all items checked
- Request changes for failures
- Approve when all items pass
During Optimization
Periodic Audit:
- Run all checklists against existing config
- Identify gaps or outdated content
- Update to meet current standards
- Document improvements made
Quality Metrics
Per-Artifact Quality Score
Formula: (Checked Items / Total Items) * 100
Thresholds:
- 100%: Excellent - production ready
- 85-99%: Good - minor improvements needed
- 70-84%: Fair - significant gaps to address
- <70%: Poor - major rework required
Overall Configuration Health
Aggregate score across all:
- Agent files
- Skill files
- Pattern files
- CLAUDE.md
Target: ≥90% average across all artifacts
Continuous Improvement
After Every Project Completion
Review and Update:
Quarterly Configuration Audit
Systematic Review:
- Run all checklists on all files
- Calculate quality scores
- Identify lowest-scoring artifacts
- Prioritize improvements
- Update and re-validate
References
Anthropic Documentation
Internal Documentation
- Knowledge Organization:
.claude/skills/reference-knowledge/knowledge-organization-strategy/SKILL.md
- Agent README:
.claude/agents/README.md
- claude-code-expert:
.claude/agents/specialists/claude-code-expert.md
Version: 1.0.0
Last Updated: 2025-10-21
Next Review: 2026-01-21
Source: Extracted from PR #164 (your-org/da-agent-hub)
Maintainer: ADLC Platform Team
