---
name: skill-lint
description: Run comprehensive validation on skills to check structural requirements and trigger quality
---

# /skill-lint

Validate skill definitions across the repository by running structural checks and semantic analysis of trigger clauses.

## What This Command Does

This command performs comprehensive validation of skills to ensure they follow structural requirements and have high-quality trigger clauses that align with Claude's cognitive architecture. It helps maintain consistency and quality across all skills in the repository.

## How It Works

When you use `/skill-lint [--plugin <name>|--all]`, Claude will:

1. **Run structural validation**: Execute the validation scripts to check for:
   - Numbered trigger format in descriptions: `(1) trigger, (2) trigger`
   - Skill name fields matching directory names
   - README skill counts matching filesystem reality

2. **Extract skill descriptions**: Get the YAML output of all skill names and descriptions

3. **Analyze trigger quality**: Semantically examine triggers for common issues described in `/Users/nke/projects/ai/thinkies/docs/contributors/writing-when-clauses.md`:
   - Introspection-based triggers ("when you notice", "when you feel", "when you sense")
   - Vague or generic triggers ("when appropriate", "when needed")
   - Internal state references ("feels", "seems", emotional states)
   - Ensure triggers reference observable context, not internal states

4. **Report findings**: Group issues by severity:
   - Structural errors that must be fixed
   - Semantic warnings about trigger quality
   - Actionable suggestions for improvements

## When to Use This Command

Use `/skill-lint` when you want to:
- Validate skills before committing changes
- Check trigger quality across the repository
- Identify skills that need trigger improvements
- Ensure consistency across skill definitions
- Verify structural requirements are met

## Example Usage

```
User: /skill-lint --all

Claude: Running comprehensive skill validation across all plugins...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STRUCTURAL VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Numbered trigger format: All 51 skills pass
✓ Skill name matching: All skills pass
✓ Skill references: All references valid
✓ README skill counts: All counts accurate

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SEMANTIC ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠ Trigger Quality Issues (8 skills):

HIGH PRIORITY - Introspection-based triggers:
  • introspect-cycle-detect:
    Trigger: "(1) when you notice yourself having the same thought"
    Issue: Uses "notice yourself" - introspective language
    Fix: "When the same reasoning appears in multiple recent responses"

  • metacognitive-knowledge-check:
    Trigger: "(2) when you feel uncertain but can't pinpoint the source"
    Issue: Uses "feel uncertain" - internal state reference
    Fix: "When the response requires unverified information"

MEDIUM PRIORITY - Vague triggers:
  • creativity-scamper:
    Trigger: "(1) when appropriate for ideation"
    Issue: "when appropriate" is too vague
    Fix: Be specific about task characteristics that call for this

  • dialogue-thinking-together:
    Trigger: "(2) when needed for collaboration"
    Issue: "when needed" lacks concrete criteria
    Fix: Describe observable conversation patterns

LOW PRIORITY - Could be more specific:
  • analysis-decompose:
    Trigger: "(1) when problems are complex"
    Note: "complex" could be more concrete
    Suggestion: "When the problem has multiple interdependent components"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Structural validation: All checks passed
⚠ Semantic analysis: 8 skills need trigger improvements
  - 2 high priority (introspection-based)
  - 3 medium priority (vague triggers)
  - 3 low priority (could be more specific)

See /Users/nke/projects/ai/thinkies/docs/contributors/writing-when-clauses.md
for guidance on writing effective triggers.
```

## Validation Scope

**Structural checks** (must pass):
- `/Users/nke/projects/ai/thinkies/.claude/scripts/extract-skill-descriptions.sh --validate`
- `/Users/nke/projects/ai/thinkies/.claude/scripts/check-skill-names.sh`
- `/Users/nke/projects/ai/thinkies/.claude/scripts/check-skill-refs.sh`
- `/Users/nke/projects/ai/thinkies/.claude/scripts/check-skill-counts.sh`

**Semantic analysis** (warnings):
- Introspection verbs: notice, catch, sense, realize, find yourself, become aware
- Emotional/state language: overwhelmed, stuck, confused, frustrated, feel, seems
- Internal experience: feeling X, vague feeling, something feels off, intuition
- Vague triggers: when appropriate, when needed, when helpful
- Generic context: when complex, when difficult, when unclear

## Options

- `--plugin <name>`: Validate skills in a specific plugin
- `--all`: Validate all plugins (thinkies, software)
- No arguments: Validate the thinkies plugin by default