Skill-Augmented LLM Agents

LeafMesh agents can be augmented with skills — domain knowledge or operating procedures the LLM reads on demand. Skills use Anthropic's open-source SKILL.md format and are managed by a central library that's safe to autoscale across replicas.

How it works

Skills live in a central library, referenced by name from each agent's YAML. Two connector kinds ship out of the box:

hosted — Redis-backed, shared across all replicas. Recommended for production.
filesystem — Reads from a local ./skills/ folder. Dev-only — each replica reads its own disk.

Additional connectors (S3, Mongo, Postgres, BYO custom) plug into the same interface.

Quick Start

Out of the box (no config)

The SDK auto-creates a default hosted source on boot. Upload a skill from Studio's Skills page, then reference it from any agent:

# Reference it from an agent
agents:
  greeter_agent:
    name: greeter_agent
    agent_type: llm
    model: gpt-4o-mini
    prompt: ...
    skills:
      - tone-rules                # shortform — uses the "default" source

Explicit source (longform)

agents:
  greeter_agent:
    name: "greeter_agent"
    skills:
      sourceName: my_library      # named source registered separately
      enabled: true
      names:
        - tone-rules
        - escalation-policy

Source management

Sources are registered and managed through Studio's Skills page (or, programmatically, the public SDK helpers). A default hosted source is auto-created on boot, so most projects don't need to register anything extra.

Connector	Storage	Autoscale-safe
`hosted`	Redis-backed central library	Yes — all replicas share the same store
`filesystem`	Project's `./skills/` folder	Dev only — each replica reads its own disk

The filesystem path is a convention, not a config knob — skills live in ./skills/ (relative to the process working directory) the same way agents live in ./agents/. There's a LEAFMESH_SKILLS_DIR env var for ops (Docker volume mounts, etc.).

Skill management

Use Studio's Skills page to upload, browse, edit, and delete skills. Cache invalidation is automatic on edit or delete.

Adaptive TTL caching

The read path depends on the connector kind:

Local source of truth (hosted, filesystem) — no cache layer. Reads go straight to the source.
Remote source of truth — reads pass through an adaptive cache. Skills used regularly are kept warm automatically, and heavy-use skills are effectively pinned — round-trips disappear for hot paths. The base cache lifetime reads from REDIS_DEFAULT_TTL in your .env.

There is no per-source TTL override; cache lifetime is a system-wide setting. To cache remote skills longer, increase REDIS_DEFAULT_TTL. Cache invalidation happens automatically on edit or delete.

Lazy vs Eager Delivery — per skill

Delivery is decided per skill, in config:

Mode	Behavior
Lazy (default)	System prompt carries only `name + description` (~50 tokens/skill); the LLM calls `load_skill_reference` when it needs a body
Eager	The full skill body ships inline in the system prompt — better latency, larger prompts. On Anthropic / Bedrock / Vertex, eager bodies get the prompt-cache discount automatically

Mark the skills that should ship eagerly with the longform eager: list — everything else stays lazy:

agents:
  support_agent:
    name: "support_agent"
    skills:
      names:
        - refund-policy        # small, used every turn → eager
        - escalation-matrix
        - product-catalog      # large, occasionally needed → lazy
      eager:
        - refund-policy
        - escalation-matrix

The shortform (skills: [a, b, c]) keeps everything lazy. skills_eager: true on the agent flips the whole set eager when that's genuinely what you want. Studio shows an eager/lazy chip per attached skill; the Playground has the same control so you can compare both deliveries live.

Roadmap

S3 / Mongo / Postgres connectors
Skill version history
Multi-file skill upload via the Skills UI

Skills — a central library with adaptive-TTL caching