Skills Routing
Mega Brain’s skills system provides automatic skill activation based on keyword detection in user prompts. Skills are modular instruction sets that enhance Claude’s capabilities for specific tasks.Overview
The skills routing system consists of three components:Architecture
Directory Structure
Skill Lifecycle
SessionStart: Index Skills
skill_indexer.py hook scans .claude/skills/ and generates SKILL-INDEX.json:SKILL.md Format
Every skill must have aSKILL.md file with this structure:
The header metadata (Auto-Trigger, Keywords, Prioridade) is required for auto-detection.
Keyword Matching
Matching Algorithm
Matching Rules
Substring Matching
Substring Matching
Keywords match as substrings (case-insensitive):
| Keyword | Matches |
|---|---|
"agent" | ”create agent”, “agent creation”, “novo agent” |
"doc" | ”documentation”, “docs”, “write doc” |
"pipeline" | ”run pipeline”, “pipeline process” |
Priority Ordering
Priority Ordering
When multiple skills match, priority determines activation order:
Example:
| Priority | Use Case | Activation |
|---|---|---|
| ALTA | Core operations (agents, pipeline, docs) | Always first |
| MÉDIA | Domain-specific (finance, sales) | After ALTA |
| BAIXA | Utilities and helpers | Last resort |
Multiple Keywords
Multiple Keywords
Skills can have multiple keywords for better coverage:All keywords are indexed independently:
Naming Convention
Mega Brain uses a HYBRID naming convention:- Core Skills (00-11)
- Domain Skills (Semantic)
Numbered for guaranteed load order:
| Number | Skill | Purpose |
|---|---|---|
| 00 | SKILL-CREATOR | Create new skills |
| 01 | DOCS-MEGABRAIN | Documentation |
| 02 | PYTHON-MEGABRAIN | Python scripts |
| 03 | AGENT-CREATION | Create agents |
| 04 | KNOWLEDGE-EXTRACTION | Extract insights |
| 05 | PIPELINE-JARVIS | Pipeline processing |
| 06 | BRAINSTORMING | Ideation |
| 07 | DISPATCHING-PARALLEL | Parallel agents |
| 08 | EXECUTING-PLANS | Execute plans |
| 09 | WRITING-PLANS | Write plans |
| 10 | VERIFICATION | Validation |
| 11 | USING-SUPERPOWERS | Advanced features |
Core skills (00-11) are loaded in numerical order for predictable precedence.
Creating Skills
Quick Start
Skill Template
Use the template from.claude/skills/_TEMPLATES/SKILL-WRITER-GUIDE.md:
Skill Best Practices
Rules
Rules
- ✅ Always test skills before deployment
- ❌ Never hard-code file paths
Validation Checklist
Validation Checklist
- Keywords are specific and unique
- Auto-trigger conditions are clear
- Skill activates on test prompts
Troubleshooting
Troubleshooting
Problem: Skill not activating
Solution: Check keyword matching in SKILL-INDEX.json and ensure priority is set
Skill Registry
Active Skills
Mega Brain ships with 37 active skills (12 core + 25 domain):Core Skills (00-11)
Core Skills (00-11)
| # | Skill | Keywords | Priority |
|---|---|---|---|
| 00 | SKILL-CREATOR | criar skill, nova skill | ALTA |
| 01 | DOCS-MEGABRAIN | documentar, md, playbook | ALTA |
| 02 | PYTHON-MEGABRAIN | python, script, codigo | ALTA |
| 03 | AGENT-CREATION | criar agente, novo agent | ALTA |
| 04 | KNOWLEDGE-EXTRACTION | extrair, insight, chunk | ALTA |
| 05 | PIPELINE-JARVIS | processar, pipeline, jarvis | ALTA |
| 06 | BRAINSTORMING | brainstorm, ideias | MEDIA |
| 07 | DISPATCHING-PARALLEL | paralelo, dispatch, batch | ALTA |
| 08 | EXECUTING-PLANS | executar, plano | ALTA |
| 09 | WRITING-PLANS | plano, planejamento | MEDIA |
| 10 | VERIFICATION | verificar, validar, checklist | ALTA |
| 11 | USING-SUPERPOWERS | superpower, avancado | MEDIA |
Domain Skills (25)
Domain Skills (25)
| Skill | Keywords | Priority |
|---|---|---|
| chronicler | briefing, handoff, log | ALTA |
| github-workflow | github, issue, PR | ALTA |
| jarvis | jarvis, orquestrador | ALTA |
| jarvis-briefing | briefing, status | ALTA |
| verify-6-levels | verificar, 6 levels | ALTA |
| ask-company | company, empresa | MEDIA |
| executor | executar, tarefa | MEDIA |
| save | save, salvar | MEDIA |
| resume | resume, retomar | MEDIA |
| (20 more…) | … | MEDIA |
Detection Protocol
FromDETECTION-PROTOCOL.md:
Advanced Features
Sub-Agents
Skills v2.0 supports sub-agents in addition to skills:| Feature | Skills | Sub-Agents |
|---|---|---|
| File | SKILL.md | AGENT.md + SOUL.md |
| Purpose | Instructions | Full agent persona |
| Location | .claude/skills/ | .claude/jarvis/sub-agents/ |
| Type | "skill" | "sub-agent" |
| Hierarchy | Standalone | Reports to JARVIS |
Dependencies
Skills can declare dependencies:Skill Graph
FromSKILL-REGISTRY.md:
Debugging Skills
Common Issues
Skill Not Detected
Skill Not Detected
Problem: Skill exists but doesn’t activateSolutions:
- Verify SKILL.md header has all required fields
- Check keyword spelling (case-insensitive but must match)
- Ensure folder doesn’t start with
_ - Restart Claude to rebuild index
- Check
.claude/mission-control/SKILL-INDEX.json
Wrong Skill Activates
Wrong Skill Activates
Problem: Different skill activates than expectedSolutions:
- Check keyword conflicts in
SKILL-INDEX.json - Adjust priority (ALTA > MÉDIA > BAIXA)
- Use more specific keywords
- Use multi-word keywords to reduce false positives
Skill Index Empty
Skill Index Empty
Problem:
SKILL-INDEX.json is empty or missingSolutions:- Check if
skill_indexer.pyran (SessionStart hook) - Verify
.claude/skills/exists and has folders - Run manually:
python3 .claude/hooks/skill_indexer.py - Check for Python errors in hook logs
Related Documentation
Hooks System
Learn about the hook system that powers skill routing
Agent Creation
Create agents that work with the skill system
Validation
Validate skill structure and content
Writing Skills
Complete guide to writing new skills
