• YAML frontmatter is valid
• Required fields are present
• Naming conventions are followed
• File structure is correct

• Evaluating description clarity and specificity
• Analyzing tool permission appropriateness
• Assessing auto-invoke trigger effectiveness
• Reviewing security implications
• Measuring usability and developer experience
• Identifying optimization opportunities

• Claude-component-builder creates or enhances a component
• User asks "is this agent/skill good quality?"
• Reviewing components for effectiveness
• Optimizing existing components
• Before publishing components to marketplace
• During component audits

• Specific about when to invoke
• Clear capability statements
• Well-defined triggers
• Concrete examples

• Vague or generic
• No clear triggers
• Ambiguous purpose
• Missing context

❌ Bad: "Helps with testing"
✓ Good: "Expert at writing Jest unit tests. Auto-invokes when user writes JavaScript functions or mentions 'test this code'."

• Minimal necessary tools
• Each tool justified
• No dangerous combinations
• Read-only when possible

• Excessive permissions
• Unjustified Write/Bash access
• Security risks
• Overly broad access

❌ Bad: allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
     (Why does a research skill need Write and Bash?)

✓ Good: allowed-tools: Read, Grep, Glob
     (Research only needs to read and search)

❌ Critical: Agent with Task tool
     (Subagents cannot spawn other subagents - Task won't work)

   Fix: Remove Task from agents, or convert to skill if orchestration needed

• Specific, unambiguous triggers
• Low false positive rate
• Catches all relevant cases
• Clear boundary conditions

• Too vague to match
• Will trigger incorrectly
• Misses obvious cases
• Conflicting with other components

❌ Bad: "Use when user needs help"
     (Too vague, when don't they need help?)

✓ Good: "Auto-invokes when user asks 'how does X work?', 'where is Y implemented?', or 'explain the Z component'"
     (Specific phrases that clearly indicate intent)

• Minimal necessary permissions
• Input validation considered
• No dangerous patterns
• Safe defaults
• Security best practices

• Unrestricted tool access
• No input validation
• Dangerous command patterns
• Security vulnerabilities

❌ Bad: Bash tool with user input directly in commands
     (Risk of command injection)

✓ Good: Read-only tools with validated inputs
     (Minimal attack surface)

• Clear documentation
• Usage examples
• Helpful error messages
• Good variable naming
• Intuitive behavior

• Confusing documentation
• No examples
• Unclear behavior
• Poor naming
• Unexpected side effects

❌ Bad: No examples, unclear parameters
✓ Good: Multiple usage examples, clear parameter descriptions

• Agent: *.md in agents/
• Skill: SKILL.md in skills/*/
• Command: *.md in commands/
• Hook: hooks.json

undefined

• Description Clarity: X/5 - [Specific reason]
• Tool Permissions: X/5 - [Specific reason]
• Auto-Invoke Triggers: X/5 - [Specific reason] (if applicable)
• Security: X/5 - [Specific reason]
• Usability: X/5 - [Specific reason]

undefined

• [Issue 1: Description and impact]
• [Issue 2: Description and impact]

• [Issue 1: Description and impact]
• [Issue 2: Description and impact]

• [Issue 1: Description and impact]

undefined

• When should this agent be invoked vs. doing inline?
• Are tools appropriate for the agent's mission?
• Does agent have Task tool? (Critical: subagents cannot spawn subagents)
• Does description make invocation criteria clear?
• Is the agent focused enough (single responsibility)?
• If orchestration is needed, should this be a skill instead?

• Are auto-invoke triggers specific and unambiguous?
• Will this activate at the right times?
• Is the skill documentation clear about when it activates?
• Does it have appropriate

  {baseDir}

  usage for resources?

• Is the command description clear about what it does?
• Are arguments well-documented?
• Is the prompt specific and actionable?
• Does it have clear success criteria?

• Are matchers specific enough?
• Will the hook trigger appropriately?
• Is the hook type (prompt/command) appropriate?
• Are there security implications?

• 4.5-5.0: Excellent - Ready for marketplace
• 4.0-4.4: Good - Minor improvements recommended
• 3.0-3.9: Adequate - Important improvements needed
• 2.0-2.9: Poor - Significant issues to address
• 1.0-1.9: Critical - Major overhaul required

python {baseDir}/scripts/quality-scorer.py path/to/component.md

• Automated quality scores (1-5) for each dimension
• Flagged issues (missing examples, vague descriptions, etc.)
• Comparison to quality standards

python {baseDir}/scripts/effectiveness-analyzer.py path/to/SKILL.md

• Auto-invoke trigger analysis (specificity, coverage)
• Tool permission analysis (necessity, security)
• Expected activation rate (high/medium/low)

python {baseDir}/scripts/optimization-detector.py path/to/component

• Suggested simplifications
• Performance considerations
• Resource usage optimization

{baseDir}/references/

• quality-standards.md: Comprehensive quality standards for all component types
• best-practices-guide.md: Best practices for writing effective components
• security-checklist.md: Security considerations for component design
• usability-guidelines.md: Guidelines for developer experience

• [What's good]

• [What needs improvement]

[Quote from description]

• Specificity: [High/Medium/Low]
• Coverage: [Complete/Partial/Missing]
• False Positive Risk: [Low/Medium/High]

• [Concern 1]
• [Concern 2]

• Documentation: [Clear/Unclear]
• Examples: [Present/Missing]
• Intuitiveness: [High/Low]

1. [Issue with specific location and fix]
2. [Issue with specific location and fix]

1. [Issue with suggestion]
2. [Issue with suggestion]

1. [Issue with suggestion]

• [What this component does well]
• [Good design decisions]

1. [Highest priority action]
2. [Next priority action]
3. [Additional improvements]

• Current Quality: X.X/5
• Projected Quality: X.X/5
• Improvement: +X.X points

• Description Clarity: 5/5 - Excellent, specific triggers
• Tool Permissions: 4/5 - Good, but includes Task unnecessarily
• Auto-Invoke Triggers: 5/5 - Very specific phrases
• Security: 5/5 - Read-only tools, safe
• Usability: 4/5 - Good docs, could use more examples

• Includes Task tool but doesn't explain why
• Could benefit from usage examples in description

• Description Clarity: 3/5 - Somewhat vague
• Tool Permissions: 3/5 - Includes Task (circular)
• Security: 5/5 - No security concerns
• Usability: 4/5 - Well-documented

• Description doesn't clearly state when to invoke agent vs. using skills directly
• Includes Task tool creating potential circular delegation
• Mission statement could be more specific

1. Assume validity: Component has passed technical validation
2. Focus on effectiveness: Will this component work well in practice?
3. Be specific: Quote exact issues and provide exact improvements
4. Score objectively: Use the 1-5 scale consistently
5. Prioritize issues: Critical > Important > Minor
6. Provide examples: Show before/after for each suggestion
7. Consider context: Marketplace components need higher standards
8. Think holistically: How does this fit in the ecosystem?

• Quality ≠ Correctness: Valid components can still be low quality
• Subjective but principled: Use framework consistently
• Constructive feedback: Focus on improvement, not criticism
• Actionable suggestions: Every issue needs a concrete fix
• Context matters: Standards vary by use case (internal vs. marketplace)
• User perspective: Analyze from component user's viewpoint