Intent to Skill Mapping in AGENTS.md: How AI Agents Route Requests to OpenCode Skills

The AGENTS.md specification uses a declarative intent-to-skill mapping table that translates high-level user intents (like "add a feature" or "debug a bug") into specific OpenCode skill invocations without requiring explicit slash commands.

In the addyosmani/agent-skills repository, intent to skill mapping serves as the routing layer between natural language requests and executable skill workflows. Instead of hardcoding routing logic in source files, the specification centralizes this mapping in AGENTS.md as a documentation-driven contract that AI agents interpret at runtime.

How Intent to Skill Mapping Works in AGENTS.md

The mapping operates as a declarative lookup table defined in the "Intent → Skill Mapping" section of AGENTS.md. When an AI coding agent receives a request, it analyzes the user's intent to categorize it into predefined buckets like "feature", "planning", "bug", or "refactoring", then selects the corresponding OpenCode skill(s) from the table.

This approach creates implicit routing—agents do not require explicit commands like /spec or /plan. Instead, they follow the Lifecycle Mapping (DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP) and, at each stage, invoke the appropriate skill based on the detected intent category.

The Intent to Skill Mapping Table

The authoritative mapping lives in AGENTS.md and pairs user intent categories with specific skill pipelines:

User intent category	Skill invoked
Feature / new functionality	spec-driven-development → incremental-implementation → test-driven-development
Planning / breakdown	planning-and-task-breakdown
Bug / failure / unexpected behavior	debugging-and-error-recovery
Code review	code-review-and-quality
Refactoring / simplification	code-simplification
API or interface design	api-and-interface-design
UI work	frontend-ui-engineering

The workflow proceeds through four stages: parse the request to identify the intent category, lookup the intent in the mapping table, invoke the corresponding skill(s) using the OpenCode skill tool, and execute the skill's internal workflow before advancing to the next lifecycle phase.

Implementation: Routing Logic for Agents

Because the mapping is documentation-based rather than executable code, agent implementations must provide their own dispatcher logic to interpret the AGENTS.md specification.

Python Dispatcher Example

The following Python implementation demonstrates how to translate natural language requests into the skill pipelines defined in AGENTS.md:

# Dispatcher (illustrative only – not part of the repo)

intent_to_skill = {
    "feature": ["spec-driven-development", "incremental-implementation", "test-driven-development"],
    "planning": ["planning-and-task-breakdown"],
    "bug": ["debugging-and-error-recovery"],
    "review": ["code-review-and-quality"],
    "refactor": ["code-simplification"],
    "api-design": ["api-and-interface-design"],
    "ui": ["frontend-ui-engineering"],
}

def select_skills(user_intent):
    # Simplify intent to the keys above

    key = {
        "add feature": "feature",
        "new functionality": "feature",
        "plan": "planning",
        "breakdown": "planning",
        "bug": "bug",
        "failure": "bug",
        "review": "review",
        "refactor": "refactor",
        "simplify": "refactor",
        "api design": "api-design",
        "interface design": "api-design",
        "ui work": "ui",
    }.get(user_intent.lower(), None)

    return intent_to_skill.get(key, [])

# Example usage

requested_intent = "I need to debug a crash in the auth flow"
skills = select_skills(requested_intent)   # → ["debugging-and-error-recovery"]

print(skills)

Bash Implementation Example

For shell-based agent runtimes, a case statement provides equivalent routing functionality:

# Assume $INTENT holds the simplified intent keyword

case "$INTENT" in
  feature)   SKILLS=("spec-driven-development" "incremental-implementation" "test-driven-development") ;;
  planning)  SKILLS=("planning-and-task-breakdown") ;;
  bug)       SKILLS=("debugging-and-error-recovery") ;;
  review)    SKILLS=("code-review-and-quality") ;;
  refactor)  SKILLS=("code-simplification") ;;
  api-design)SKILLS=("api-and-interface-design") ;;
  ui)        SKILLS=("frontend-ui-engineering") ;;
  *)         SKILLS=() ;;
esac

# Invoke each skill via the OpenCode `skill` tool

for s in "${SKILLS[@]}"; do
  skill "$s"
done

Key Files and Their Roles

The intent to skill mapping system spans three primary file types in the repository:

• AGENTS.md — Contains the authoritative mapping table and lifecycle guidance that defines which skills correspond to which intents.
• skills/*/SKILL.md — Individual skill definitions (e.g., skills/spec-driven-development/SKILL.md) that provide detailed workflow instructions once a skill is selected.
• skills/*/scripts/*.sh — Executable skill scripts (e.g., skills/spec-driven-development/scripts/implement.sh) that run the concrete steps after intent routing occurs.

Summary

• AGENTS.md defines a declarative intent-to-skill mapping table that maps user intents (feature, bug, planning) to specific OpenCode skills.
• The routing is implicit—agents parse natural language and follow the DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP lifecycle without explicit slash commands.
• Multi-skill pipelines exist for complex intents like "feature", which chains spec-driven-development, incremental-implementation, and test-driven-development.
• Agent implementations must provide their own dispatcher logic to interpret the AGENTS.md specification at runtime.

Frequently Asked Questions

How does an agent determine which skill to invoke without explicit commands?

The agent analyzes the natural language request to categorize it into predefined intent buckets (feature, bug, planning, etc.) defined in AGENTS.md. It then performs a lookup in the intent-to-skill mapping table and invokes the corresponding skill(s) automatically, eliminating the need for explicit slash commands like /spec or /debug.

Can multiple skills be triggered for a single user intent?

Yes. The mapping supports skill chaining for complex workflows. For example, the "feature" intent triggers a sequence of three skills: spec-driven-development, followed by incremental-implementation, and finally test-driven-development, ensuring comprehensive coverage from specification through testing.

Where is the actual routing logic implemented if it's not in AGENTS.md?

While AGENTS.md contains the declarative specification, the actual dispatch logic resides in the agent's runtime implementation. Developers must implement lookup functions (in Python, Bash, or other languages) that parse user input, query the mapping table conceptually, and invoke the OpenCode skill tool with the appropriate skill names.

What happens if a user request doesn't match any intent category in the table?

The specification implies that agents should handle unmatched intents gracefully. In the provided code examples, unrecognized intents return empty skill lists or fall through to default cases, allowing the agent to either request clarification or apply a default behavior defined by the specific runtime implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}