intent-detection

Purpose

Automatically detect user intent and route to the appropriate agent with full transparency.

Detection Algorithm

1. Input Analysis

User Input: "Go 코드 리뷰해줘"
            │
            ▼
┌─────────────────────────────┐
│  Tokenize & Extract         │
├─────────────────────────────┤
│  Keywords: ["Go"]           │
│  Actions: ["리뷰"]          │
│  File refs: []              │
│  Context: []                │
└─────────────────────────────┘

2. Pattern Matching

Match extracted tokens against agent triggers:

# For each agent in agent-triggers.yaml
match_score = 0

# Keyword match
for keyword in user_keywords:
  if keyword in agent.keywords:
    match_score += agent.keyword_weight (default: 40)

# Action match
for action in user_actions:
  if action in agent.actions:
    match_score += agent.action_weight (default: 40)

# File pattern match
for pattern in user_file_refs:
  if matches(pattern, agent.file_patterns):
    match_score += agent.file_weight (default: 30)

# Context bonus
if agent == recent_agent:
  match_score += context_bonus (default: 10)

3. Confidence Calculation

confidence = min(100, match_score)

4. Decision

if confidence >= 90:
    auto_execute()
elif confidence >= 70:
    request_confirmation()
else:
    list_options()

Detection Patterns

Keyword Patterns

# Korean keywords
korean:
  - "고" → go
  - "파이썬" → python
  - "러스트" → rust
  - "타입스크립트" → typescript

# Action verbs (Korean)
actions_kr:
  - "리뷰" → review
  - "분석" → analyze
  - "수정" → fix
  - "생성" → create
  - "만들어" → create
  - "확인" → check

File Pattern Matching

patterns:
  go: ["*.go", "go.mod", "go.sum"]
  python: ["*.py", "requirements.txt", "pyproject.toml", "setup.py"]
  rust: ["*.rs", "Cargo.toml"]
  typescript: ["*.ts", "*.tsx", "tsconfig.json"]
  kotlin: ["*.kt", "*.kts", "build.gradle.kts"]

Output Format

High Confidence

[Intent Detected]
├── Input: "Go 코드 리뷰해줘"
├── Agent: lang-golang-expert
├── Confidence: 95%
└── Reason: "Go" keyword + "리뷰" action

┌─ Agent: lang-golang-expert (sw-engineer)
└─ Task: Code review

Medium Confidence

[Intent Detected]
├── Input: "백엔드 API 확인해줘"
├── Detected: be-go-backend-expert (?)
├── Confidence: 78%
└── Alternatives available

Select agent:
  1. be-go-backend-expert (78%)
  2. be-fastapi-expert (72%)
  3. be-springboot-expert (68%)

Choice [1-3, or agent name]:

Override

[Override Detected]
├── Input: "@lang-python-expert review api.py"
├── Agent: lang-python-expert (explicit)
└── Bypassing intent detection

┌─ Agent: lang-python-expert (sw-engineer)
└─ Task: Review api.py

Integration

With Secretary

Secretary uses this skill to:
1. Parse incoming user requests
2. Detect intent and select agent
3. Display reasoning
4. Handle confirmations
5. Route to selected agent

With Agent Triggers

Load triggers from:
.claude/skills/intent-detection/patterns/agent-triggers.yaml

Each agent defines:
- keywords (language names, tech terms)
- file_patterns (extensions, config files)
- actions (supported actions)
- weights (scoring factors)

With Skill Triggers

Skill triggers are defined in agent-triggers.yaml alongside agent triggers.
Each skill trigger has a `routing_rule` field that specifies which skill to invoke.

When a skill trigger matches with confidence >= 70%:
1. Display the intent detection output with skill name
2. Invoke the skill via Skill tool instead of spawning an agent
3. If confidence < 70%, list skill options for user selection

Skill triggers use the `skill-` prefix in their YAML key to distinguish
from agent triggers.

Error Handling

No Match (< 30% confidence)

Generic task (no identifiable domain):

[Intent Unclear]
├── Input: "도와줘"
├── Confidence: < 30%
└── Too generic to detect intent

How can I help? Please be more specific:
- What type of task? (review, create, fix, ...)
- What language/technology? (Go, Python, ...)
- What file or project?

Specialized task with identifiable domain (keywords/files detected but no matching agent):

[No Matching Agent]
├── Input: "Terraform 모듈 리뷰해줘"
├── Domain: terraform (detected from keywords)
├── Matching Agent: none
└── Action: Trigger dynamic agent creation

→ Delegating to mgr-creator with context:
  domain: terraform
  keywords: ["terraform", "모듈"]
  file_patterns: ["*.tf"]

Ambiguous Match

[Intent Ambiguous]
├── Input: "코드 리뷰"
├── Top matches:
│   └── All experts: ~50% each
└── Need file context or language hint

Specify the language or provide a file path.

Configuration

intent_detection:
  enabled: true
  auto_execute_threshold: 90
  confirm_threshold: 70
  show_reasoning: true
  max_alternatives: 3
  korean_support: true

Research Intent Routing

When a research/information gathering intent is detected:

Detection Keywords

# Korean
korean:
  - "조사" → research
  - "검색" → search
  - "리서치" → research
  - "탐색" → explore
  - "찾아" → look up
  - "알아봐" → find out
  - "자료" → gather materials
  - "정보 수집" → gather information

# English
english:
  - "research"
  - "investigate"
  - "search for"
  - "look up"
  - "gather information"

Routing Logic

Research intent detected (confidence >= 70%)
    ↓
Check Codex CLI availability
    ├─ Available (codex binary + OPENAI_API_KEY)
    │   → Use codex-exec skill with --effort xhigh
    │   → Prompt: "Research and analyze: {user_request}"
    │   → Returns: structured findings for orchestrator
    └─ Unavailable
        → Fall back to Claude's WebFetch/WebSearch
        → Orchestrator handles directly or via general-purpose agent

Confidence Scoring

Factor	Weight	Example
Research keyword match	+40	"조사해줘", "research"
Action verb match	+30	"찾아", "investigate"
URL/topic present	+20	specific URL or topic mentioned
Context (previous research)	+10	follow-up research request

Output Format

[Intent Detected]
├── Input: "{user input}"
├── Workflow: research-workflow
├── Confidence: {percentage}%
├── Method: codex-exec (xhigh) | WebFetch fallback
└── Reason: {explanation}

When spawning agents via the Agent tool during this skill's execution, always pass mode: "bypassPermissions". The Agent tool default (acceptEdits) overrides agent frontmatter permissionMode, causing permission prompts during unattended execution.