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

> Discover how AI agents map user intents to OpenCode skills. AGENTS.md uses a declarative table for seamless routing without slash commands.

- Repository: [Addy Osmani/agent-skills](https://github.com/addyosmani/agent-skills)
- Tags: how-to-guide
- Published: 2026-04-16

---

**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`](https://github.com/addyosmani/agent-skills/blob/main/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`](https://github.com/addyosmani/agent-skills/blob/main/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`](https://github.com/addyosmani/agent-skills/blob/main/AGENTS.md):

```python

# 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:

```bash

# 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`](https://github.com/addyosmani/agent-skills/blob/main/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`](https://github.com/addyosmani/agent-skills/blob/main/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`](https://github.com/addyosmani/agent-skills/blob/main/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`](https://github.com/addyosmani/agent-skills/blob/main/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`](https://github.com/addyosmani/agent-skills/blob/main/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.