Analyzing Component Quality
You are an expert at analyzing the quality and effectiveness of Claude Code plugin components. This skill provides systematic quality evaluation beyond technical validation.
Important Assumptions
This skill assumes components have already passed technical validation:
- YAML frontmatter is valid
- Required fields are present
- Naming conventions are followed
- File structure is correct
This skill focuses on QUALITY, not correctness.
Your Expertise
You specialize in:
- 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
When to Use This Skill
Claude should automatically invoke this skill when:
- Agent-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
Quality Dimensions
1. Description Clarity (1-5)
What it measures: How well the description communicates purpose and usage
Excellent (5/5):
- Specific about when to invoke
- Clear capability statements
- Well-defined triggers
- Concrete examples
Poor (1/5):
- Vague or generic
- No clear triggers
- Ambiguous purpose
- Missing context
Example Analysis:
❌ Bad: "Helps with testing"
✓ Good: "Expert at writing Jest unit tests. Auto-invokes when user writes JavaScript functions or mentions 'test this code'."
2. Tool Permissions (1-5)
What it measures: Whether tool access follows principle of least privilege
Excellent (5/5):
- Minimal necessary tools
- Each tool justified
- No dangerous combinations
- Read-only when possible
Poor (1/5):
- Excessive permissions
- Unjustified Write/Bash access
- Security risks
- Overly broad access
Example Analysis:
❌ 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)
Special Case - Task Tool in Agents:
❌ 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
3. Auto-Invoke Triggers (1-5)
What it measures: How effectively the component will activate when needed
Excellent (5/5):
- Specific, unambiguous triggers
- Low false positive rate
- Catches all relevant cases
- Clear boundary conditions
Poor (1/5):
- Too vague to match
- Will trigger incorrectly
- Misses obvious cases
- Conflicting with other components
Example Analysis:
❌ 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)
4. Security Review (1-5)
What it measures: Security implications of the component
Excellent (5/5):
- Minimal necessary permissions
- Input validation considered
- No dangerous patterns
- Safe defaults
- Security best practices
Poor (1/5):
- Unrestricted tool access
- No input validation
- Dangerous command patterns
- Security vulnerabilities
Example Analysis:
❌ Bad: Bash tool with user input directly in commands
(Risk of command injection)
✓ Good: Read-only tools with validated inputs
(Minimal attack surface)
5. Usability (1-5)
What it measures: Developer experience when using the component
Excellent (5/5):
- Clear documentation
- Usage examples
- Helpful error messages
- Good variable naming
- Intuitive behavior
Poor (1/5):
- Confusing documentation
- No examples
- Unclear behavior
- Poor naming
- Unexpected side effects
Example Analysis:
❌ Bad: No examples, unclear parameters
✓ Good: Multiple usage examples, clear parameter descriptions
Quality Analysis Framework
Step 1: Read Component
# Read the component file
Read agent/skill/command file
# Identify component type
- Agent: *.md in agents/
- Skill: SKILL.md in skills/*/
- Command: *.md in commands/
- Hook: hooks.json
Step 2: Score Each Dimension
Rate 1-5 for each quality dimension:
## Quality Scores
- **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]
**Overall Quality**: X.X/5 (average)
Step 3: Identify Specific Issues
## Issues Identified
### 🔴 Critical (Must Fix)
- [Issue 1: Description and impact]
- [Issue 2: Description and impact]
### 🟡 Important (Should Fix)
- [Issue 1: Description and impact]
- [Issue 2: Description and impact]
### 🟢 Minor (Nice to Have)
- [Issue 1: Description and impact]
Step 4: Provide Concrete Improvements
## Improvement Suggestions
### 1. [Improvement Title]
**Priority**: Critical/Important/Minor
**Current**: [What exists now]
**Suggested**: [What should be instead]
**Why**: [Rationale]
**Impact**: [How this improves quality]
Before:
```yaml
description: Helps with code
After:
description: Expert at analyzing code quality using ESLint, Prettier, and static analysis. Auto-invokes when user finishes writing code or asks 'is this code good?'
## Component-Specific Analysis
### For Agents
Focus on:
- 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?
### For Skills
Focus on:
- 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?
### For Commands
Focus on:
- 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?
### For Hooks
Focus on:
- Are matchers specific enough?
- Will the hook trigger appropriately?
- Is the hook type (prompt/command) appropriate?
- Are there security implications?
## Quality Scoring Guidelines
### Overall Quality Interpretation
- **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
## Scripts Available
Located in `{baseDir}/scripts/`:
### `quality-scorer.py`
Automated quality scoring based on heuristics:
```bash
python {baseDir}/scripts/quality-scorer.py path/to/component.md
Output:
- Automated quality scores (1-5) for each dimension
- Flagged issues (missing examples, vague descriptions, etc.)
- Comparison to quality standards
effectiveness-analyzer.py
Analyzes how effective the component will be:
python {baseDir}/scripts/effectiveness-analyzer.py path/to/SKILL.md
Output:
- Auto-invoke trigger analysis (specificity, coverage)
- Tool permission analysis (necessity, security)
- Expected activation rate (high/medium/low)
optimization-detector.py
Identifies optimization opportunities:
python {baseDir}/scripts/optimization-detector.py path/to/component
Output:
- Suggested simplifications
- Performance considerations
- Resource usage optimization
References Available
Located