130 lines
5.3 KiB
Markdown
130 lines
5.3 KiB
Markdown
---
|
|
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
|
|
|