gh-synapseradio-thinkies-plugins-thinkies/commands/skill-lint.md

name, description

name	description
skill-lint	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