analyzing-component-quality

What this skill does

# 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

```bash
# 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:

```markdown
## 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

```markdown
## 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

```markdown
## 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:
```yaml
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:
```bash
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:
```bash
python {baseDir}/scripts/optimization-detector.py path/to/component
```

**Output**:
- Suggested simplifications
- Performance considerations
- Resource usage optimization

## References Available

Locate