RecursiveSkilledAgent

Runtime Entry Surface

If LLMAgent is the general mediation layer for model calls, RecursiveSkilledAgent is the runtime coordinator that turns those calls into bounded skill execution. Its role is not to reimplement the logic of every skill family. It is to keep discovery, routing, context injection, and delegation under one explicit entry surface so that the actual execution discipline can remain family-specific.

This distinction matters architecturally. The agent does not flatten DBTable skills, orchestration skills, MCP skills, Anthropic skills, dynamic code generation skills, and code skills into one generic behavior. It discovers which family a skill belongs to from the descriptor filename, asks the matching subsystem to parse and prepare the skill, and later delegates execution back to that subsystem. The result is a unified runtime entry point without a monolithic execution model. The taxonomy behind those families is documented in Subsystems and Skills.

The word recursive is therefore literal rather than decorative. A prompt handled by RecursiveSkilledAgent may invoke an orchestrator, that orchestrator may invoke other skills, and those skills may in turn open further bounded execution paths. The agent remains the shared coordinator of registration, selection, and context, while the lower-level behavior stays inside the subsystem that owns it.

Discovery, Registration, and Preparation

Skill discovery is filesystem-driven. The agent starts from its configured roots, asks the discovery service to scan for descriptor filenames such as SKILL.md, dcgskill.md, cskill.md, mskill.md, oskill.md, and tskill.md, and constructs a skill record for each discovered bundle. If a directory already contains one of those descriptor files, that directory is treated as a concrete skill bundle. If not, discovery recurses into nested directories until such a descriptor is found.

After discovery, the agent registers each skill under a canonical name derived from the parsed descriptor name or the folder short name, together with a set of aliases used later for lookup. Registration does not stop at metadata. The matching subsystem is immediately asked to parse the descriptor and, when that subsystem supports it, to prepare the skill for execution. This is also the stage at which built-in skills from the package’s internal skills/ directory are brought into the registry.

There is one important special case. The internal skill mirror-code-generator is registered first, and when a skill of type cskill is later discovered, the agent automatically schedules a preparation call through mirror-code-generator. This means that generation for Code Skills is initiated by the top-level agent during registration rather than by the Code Skills subsystem itself. The resulting preparation promises are tracked in pendingPreparations and awaited before normal execution unless the caller explicitly bypasses that wait.

Routing, Execution, and Session State

The execution path begins from one of two situations. If the caller provides an explicit skill name, the agent resolves that skill from the registry, injects default arguments when the skill family declares one, and delegates execution directly to the subsystem that owns the skill. If the caller does not provide a skill name, the runtime first runs a bounded orchestrator-selection stage through the selector service and attempts to resolve a registered orchestrator. If such an orchestrator exists, the request is delegated there. If not, the executor synthesizes an ad hoc orchestrator over the available non-orchestrator skills and executes it through the orchestrator subsystem as an agentic session, with Loop Session as default fallback and Plan SOPLang Session when configured. In other words, fallback routing still happens inside a session discipline rather than degrading into open-ended prompting. The session styles used by orchestrators are described separately in Agentic Sessions.

Shared execution context is injected before that delegation happens. If the caller has not already provided context.sessionMemory, the agent creates or retrieves the appropriate session map by checking context.sessionId, then context.user.sessionId, then context.user.sessionToken, and otherwise falling back to the default session. If the agent has configured I/O services, those are also injected into context.io. This keeps session handling and runtime I/O as shared concerns rather than forcing each skill family to rebuild them independently.

Session management itself is part of the runtime contract. The agent supports a default session for CLI-like use, additional named sessions for multi-user or webchat-style flows, manual clearing and deletion, TTL-based cleanup, LRU-style eviction when maxSessions is exceeded, and graceful shutdown through shutdown(). When enableSummary is active, top-level executions can also update a rolling conversation summary inside session memory after each completed turn.

A representative configuration therefore looks as follows.

const agent = new RecursiveSkilledAgent({
    startDir: process.cwd(),
    searchUpwards: true,
    additionalSkillRoots: ['./team-skills'],
    exposeInternalSkills: false,
    tierConfig: { plan: 'plan', execution: 'fast', code: 'code' },
    sessionConfig: { maxSessions: 1000, sessionTTL: 7_200_000, cleanupInterval: 300_000 },
    fallbackSessionType: 'loop',
    enableSummary: false,
});

The practical meaning of that configuration is straightforward. The agent scans for skills, preserves session state, can hide internal skills from LLM-based selection, and delegates planning and execution to the tiers appropriate for the selected skill family. Its purpose is not to behave like a universal assistant. Its purpose is to make skill-based execution repeatable, bounded, and inspectable at the entry level of the runtime.