Scope	Location	Purpose	Who Sets It
Plugin-level	`$CLAUDEPLUGINROOT/.claude/skills/skill-rules.json`	Plugin recommends its own skills	Plugin author
Project-level	`$CLAUDEPROJECTDIR/.claude/skills/skill-rules.json`	User configures for their project	End user

Plugin-level (Recommended for plugins with multiple skills)

Plugins with related skills SHOULD include skill-activation to help users discover relevant skills:

my-plugin/
├── hooks/hooks.json              ← UserPromptSubmit hook
├── scripts/skill-activation.py   ← Hook script
├── .claude/skills/skill-rules.json  ← Plugin's own rules
└── skills/
    ├── skill-a/
    └── skill-b/

Example: skillmaker uses plugin-level activation to suggest skill-design when user mentions "create skill".

Project-level (User-configured)

Users can add skill-activation to their own projects independently:

my-project/
├── .claude/
│   └── skills/
│       └── skill-rules.json   ← User's rules
└── settings.json              ← UserPromptSubmit hook

Quick Start

Create .claude/skills/skill-rules.json
Add UserPromptSubmit hook
Hook reads rules, matches triggers, suggests skills

Core Concept

User Prompt → [Hook] → skill-rules.json → Match triggers → Suggest skills

skill-rules.json (Minimal)

{
  "version": "1.0",
  "skills": {
    "backend-patterns": {
      "type": "domain",
      "enforcement": "suggest",
      "promptTriggers": {
        "keywords": ["backend", "API"]
      }
    }
  }
}

Skill Types

Type	Purpose
domain	Expertise/knowledge
guardrail	Enforce standards

Enforcement Levels

Level	Behavior
suggest	Recommend
warn	Allow + warning
block	Must use skill

Best Practices

Start with suggest - Don't block until proven
Specific keywords - Avoid generic over-triggering
Test regex - Verify no false positives
Use skipConditions - Allow escape hatch

References

[Full Schema](references/full-schema.md) - Complete skill-rules.json spec
[Hook Implementation](references/hook-implementation.md) - TypeScript/Bash code
[Real Examples](references/skill-rules-examples.md) - Production configs

npx skills add smithery/chkim-su --skill skill-activation-patterns