Forward Claude Code skills into AGNT's soul loader

A Claude Code skill is a markdown bundle. It has a name, description, triggering heuristics, instructions, and optional tool references. When Claude Code detects a matching intent, it routes into the skill and the skill's instructions become part of the active prompt.

AGNT's soul loader is the per-agent structural prompt assembler. It reads a set of structural keys (17 by default) plus any registered modules, and assembles them into the agent's system prompt. Modules can be injected statically (always present) or dynamically (matched per turn).

The forwarding bridge is simple: a Claude Code skill becomes a dynamic soul-loader module. The skill's description becomes the match heuristic. The instructions become the injected content. Tool references become declared tool scopes.

Start with a small, well-tested skill. A good first candidate is a simple instruction bundle — no tool calls, no multi-turn state. This keeps the forwarding logic simple while you learn the flow.

Let's use a hypothetical `dietary-substitution` skill: when a venue agent gets a question about dietary substitutions, route into the skill, which carries specific guidance on how to answer (be specific about what's in the dish, suggest alternatives, never promise a change the kitchen hasn't approved).

Claude Code skills live in `.claude/skills/<skill-name>/SKILL.md`. The file has frontmatter with the skill's metadata and a body with the instructions:

---
name: dietary-substitution
description: Use when a guest asks about dietary substitutions at a venue.
tools: [menu_lookup]
---

# Dietary Substitution Skill

When a guest asks about substitutions:
1. Look up the dish in the menu.
2. Identify the specific ingredient the guest needs to avoid.
...

Parse the frontmatter. You'll need `name`, `description`, and `tools`. The body is the instructions.

The registration call is:

curl -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dietary-substitution",
    "match_description": "Use when a guest asks about dietary substitutions at a venue.",
    "instructions": "When a guest asks about substitutions:\n1. Look up the dish...",
    "required_tools": ["menu_lookup"],
    "scope": "venue_agent"
  }' \
  https://api.agntdot.com/soul-loader/modules

`scope` tells AGNT which agent types can use the module. For a venue-specific skill, use `venue_agent`. For a consumer-facing skill (Andy), use `consumer_agent`. Use `all` only for truly universal skills.

Pick a venue agent in your fleet and send it a test message: "can I get the pasta without gluten?" Watch the agent's heartbeat log. You should see the soul loader match the `dietary-substitution` module and inject the instructions.

If the match doesn't fire, the most likely cause is a description mismatch. Run the description through the `tool-description-tightener` prompt — dynamic matching uses the same heuristics as MCP tool routing, and description quality dominates.

Soul loader caches per-agent for 1 hour (TTL from `soul_loader.py`). When you register a new module or update an existing one, the cache invalidates for all agents in scope — the next message they process will re-assemble the prompt with the new module.

This means you can update a skill and see the effect live within ~2 minutes (one agent cycle). No restart, no redeploy.

The loop closes when you realize the same skill file can live in `.claude/skills/` and power a Claude Code session at the same time it powers a production AGNT venue agent. Write the skill once — two surfaces, two workflows, zero drift.

For teams building agent platforms on top of AGNT, this is the killer feature: capability authoring becomes declarative, versioned, and portable. Your product managers can write skills in markdown and ship capability updates without touching Python.