Skip to content

How to Debug Skill Activation

This guide helps you troubleshoot when skills aren't loading or behaving as expected.

Quick Diagnostic

Run the built-in diagnostic command:

/core:doctor activation-test "your test phrase here"

This shows:

  • Which skills match your phrase
  • What triggers fired (keywords, patterns)
  • Loading order and priority

Common Issues

Issue: Skill Not Activating

Symptoms:

  • Agent doesn't apply expected behavior
  • No mention of skill in response
  • Output lacks skill-defined patterns

Diagnosis Steps:

  1. Check skill exists: 

    ls plugins/*/skills/

  2. Verify activation rules exist: 

    find plugins -name "skill-rules-fragment.json"

  3. Test keyword matching:

   /core:doctor activation-test "keyword from your prompt"
   ```

**Common Fixes:**

| Problem | Fix |
|---------|-----|
| Missing `skill-rules-fragment.json` | Create activation rules file |
| Keywords don't match prompt | Add relevant keywords to rules |
| Pattern regex is wrong | Test pattern at regex101.com |
| Skill not in installed plugin | Add plugin to marketplace.json |

---

### Issue: Wrong Skill Activates

**Symptoms:**

- Unexpected behavior in output
- Wrong tone or methodology applied
- Conflicting instructions

**Diagnosis Steps:**

1. **Check what activated:**

```bash
   /core:doctor activation-test "your exact prompt"
   ```

2. **Review priority settings:**
   ```bash
   grep -r "priority" plugins/*/skills/*/skill-rules-fragment.json
   ```

3. **Check for keyword overlap:**
   Look for common keywords across multiple skills.

**Common Fixes:**

| Problem | Fix |
|---------|-----|
| Multiple skills share keywords | Make keywords more specific |
| Priority too high | Lower priority in rules file |
| Overly broad patterns | Narrow regex patterns |

---

### Issue: Skill Loads But Doesn't Affect Output

**Symptoms:**

- Diagnostic shows skill activated
- Output doesn't reflect skill content
- Agent seems to ignore instructions

**Diagnosis Steps:**

1. **Check skill content is actionable:**
   ```bash
   cat plugins/*/skills/*/SKILL.md | head -50
   ```

2. **Verify SKILL.md isn't empty or malformed:**
   ```bash
   wc -l plugins/*/skills/*/SKILL.md
   ```

3. **Check for conflicting instructions:**
   Review CLAUDE.md and other skills for contradictions.

**Common Fixes:**

| Problem | Fix |
|---------|-----|
| Passive language | Use imperative: "Do X" not "X should be done" |
| Too abstract | Add concrete examples |
| Conflicts with CLAUDE.md | Align or prioritize instructions |
| Skill too long | Move detail to resources/, keep SKILL.md < 500 lines |

---

## Activation Rules Deep Dive

### Understanding skill-rules-fragment.json

```json
{
  "my-skill": {
    "type": "domain",
    "enforcement": "suggest",
    "priority": "high",
    "promptTriggers": {
      "keywords": ["audit", "report"],
      "intentPatterns": ["(create|write).*(report)"]
    },
    "fileTriggers": {
      "pathPatterns": ["**/reports/**"]
    }
  }
}

Trigger Types

Trigger How It Works Example
keywords Exact word match (case-insensitive) "audit" matches "Run an audit"
intentPatterns Regex match on full prompt "(create|write).*(report)"
pathPatterns Glob match on file paths "**/reports/**"

Priority Levels

Priority When Loaded Use Case
critical Always first Core standards
high Before medium/low Important domain skills
medium Default order General skills
low Last Optional enhancements

Enforcement Levels

Level Behavior
require Must load if triggered
suggest Agent decides based on context
optional Only if explicitly relevant

Testing Workflow

Step 1: Isolate the Skill

Test with a minimal prompt that should trigger only your skill:

/core:doctor activation-test "keyword1 keyword2"

Step 2: Verify Rules File

Check JSON syntax:

python -m json.tool plugins/divisions/my-plugin/skills/my-skill/skill-rules-fragment.json

Step 3: Test Regex Patterns

Use regex101.com with:

  • Flavor: ECMAScript (JavaScript)
  • Test string: Your expected prompt

Step 4: Check Hook Execution

The UserPromptSubmit hook handles activation. Verify it's configured:

cat plugins/core-dependencies/hooks/hooks.json

Step 5: Review Full Activation Chain

User Prompt
    ↓
UserPromptSubmit Hook (core-dependencies)
    ↓
Scan all skill-rules-fragment.json files
    ↓
Match keywords and patterns
    ↓
Inject activation suggestions
    ↓
Agent loads relevant skills

Logging and Debugging

Enable Verbose Mode

Some environments support verbose logging:

DEBUG=skills opencode

Manual Activation Test

Ask the agent directly:

What skills are you currently using? List them.

Check Skill Content

Read what the agent sees:

Show me the contents of the seo-methods skill

Troubleshooting Checklist

Use this checklist when skills aren't working:

  • Skill directory exists in correct location
  • SKILL.md file is present and not empty
  • skill-rules-fragment.json exists with valid JSON
  • Keywords in rules match words in your prompt
  • Regex patterns are valid (test at regex101.com)
  • Plugin is registered in marketplace.json
  • core-dependencies plugin is installed
  • No syntax errors in any JSON files
  • Skill content uses imperative language
  • No conflicting skills with higher priority

Reference

Explanation

How-To