Initial commit
This commit is contained in:
Zhongwei Li
129
commands/skill-lint.md
Normal file
129
commands/skill-lint.md
Normal file
@@ -0,0 +1,129 @@
|
||||
---
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user