@nhtio/adk/batteries/skills
Stateful skill discovery, activation, and deactivation for ADK agents.
Interfaces
| Interface | Description |
|---|---|
| CatalogEntry | A winning catalog candidate or a losing candidate retained for provenance. |
| DiscoveredSkill | Discovery result. Carries the ROUTING METADATA — name and description — because that is what list_skills shows the model and what it chooses on; requiring descriptor() to obtain it would mean loading every skill's module just to list the catalog. |
| ForgeSkillToolsOptions | Deployment-time controls for the lifecycle tools forged by forgeSkillTools. |
| LoadResult | Immediate lifecycle outcome, including the objects registered in this dispatch. |
| ProjectedSkill | The per-context projection of one initialized skill. |
| RefreshResult | Result of catalog refresh, including versions that now differ from loaded state. |
| SkillArtifactRegistry | Resolved artifact kinds plus the consumer-owned skill/tool binding table. |
| SkillDescriptor | Live, source-owned definition resolved when a catalog entry is loaded. |
| SkillIsolatedTool | Tier-2 tool whose source is evaluated inside the configured guest runtime. |
| SkillIsolationConfig | Tier-2 guest capabilities and termination/timeout controls. |
| SkillManager | Stateful skill lifecycle; construct one manager per conversation or session. |
| SkillManagerConfig | Inputs that determine discovery, projection, and the explicit containment exceptions. |
| SkillMiddlewareOptions | Options for the standalone skills middleware factories. |
| SkillMiddlewareSet | The four pipeline hooks needed to hydrate, reconcile, observe, and strip skill state. |
| SkillScriptConfig | Tier-3 execution controls, workspace, policy, and output/time ceilings. |
| SkillScriptParam | One validated value in the fixed argv contract presented to a script. |
| SkillScriptSpec | A model-selectable script bundled with a skill and invoked with declared arguments only. |
| SkillSource | Runtime-neutral source seam for discovery, metadata, body bytes, and bundled files. |
| SkillWorkspace | Skill-scoped materialization service used by tier-3 scripts. |
Type Aliases
| Type Alias | Description |
|---|---|
| SkillLoadChannel | Controls whether a loaded body is represented by a handle or rendered inline per dispatch. |
| SkillRef | A discovered skill plus manager-assigned provenance. This is what the battery passes around. |
| SkillSourceResolver | A source instance or lazy/default export resolver used during manager construction. |
| SpooledKindResolver | An artifact constructor or lazy/default-export resolver for a named skill result kind. |
Variables
| Variable | Description |
|---|---|
| E_INVALID_SKILLS_CONFIG | Fatal construction error for invalid or unsafe-to-resolve manager configuration. |
| E_SKILL_ALREADY_LOADED | Raised when load would initialize a skill that is already initialized. |
| E_SKILL_ARTIFACT_UNAVAILABLE | Raised when the selected artifact kind was not registered. |
| E_SKILL_MANIFEST_INVALID | Raised when source metadata or a descriptor violates the identity/version contract. |
| E_SKILL_NOT_FOUND | Raised when load, refresh, or unload names no winning catalog entry. |
| E_SKILL_NOT_LOADED | Raised when unload or a loaded-only operation targets an uninitialized skill. |
| E_SKILL_SCRIPT_DENIED | Explicit 403 refusal by the script policy; this is distinct from a failed gate. |
| E_SKILL_SCRIPT_FAILED | Raised when a skill script completes with a nonzero exit code and the deployment leaves SkillScriptConfig.failOnNonzeroExit at its default (true). The message carries the script name, the exit code, and the retrievable id of the spooled output so the failure is still inspectable. A deployment whose scripts use exit codes as ordinary signalling sets failOnNonzeroExit: false and receives the acknowledgement string instead. |
| E_SKILL_SCRIPT_GATE_UNAVAILABLE | 503 when the script gate fails for any reason other than an explicit denial; never misroutes an engine failure as 403. |
| E_SKILL_SCRIPT_POLICY_WIDENED | Raised when script policy derivation would widen permissions beyond the declared boundary. |
| E_SKILL_SCRIPT_TIMEOUT | Raised when a script exceeds its configured execution deadline. |
| E_SKILL_SOURCE_PATH_REJECTED | Raised when a requested bundled path is unsafe or outside the source namespace. |
| E_SKILL_TOOL_BAD_RESPONSE | Raised when a skill tool returns a value that fails response validation. |
| E_SKILL_TOOL_COLLISION | Raised when a skill tool name collides with another registered tool. |
| E_SKILL_TOOL_DUPLICATE | Raised when one skill declares the same tool name more than once. |
| E_SKILL_TOOL_FAILED | Raised when a skill tool handler fails during execution. |
| E_SKILL_WORKSPACE_FAILED | Raised when materialization or disposal of a skill workspace fails. |
Functions
| Function | Description |
|---|---|
| createSkillArtifactRegistry | Resolve all optional artifact classes eagerly. The built-in raw kind is always available; optional artifact batteries are intentionally not imported here. |
| createSkillManager | Create a skills manager. Construct one manager per conversation/session, alongside its runner; share source objects when discovery caching is desired, but never share loaded manager state. |
| createSkillMiddlewareSet | Build the stable four-middleware skills integration surface. |
| forgeSkillTools | Forge the five stateful lifecycle tools for one skill manager. |
| implementsSkillSource | Duck-guard for the synchronous portion of a source contract. discover() returns an async iterable and cannot be duck-checked beyond "is a function", so a value passing this guard may still violate the protocol. runSkillSourceConformance, from @nhtio/adk/batteries/skills/conformance, is the real protocol check. |
| parseSkillMd | Parse an agentskills.io-shaped SKILL.md for source authors. The manager's load path never calls this helper: sources own descriptor and body authority. Malformed frontmatter degrades to an empty object when it is not a delimited YAML block; malformed YAML is a manifest error. |
| renderError | Render skill runtime errors for the model; configuration errors remain fatal. |
| skillsDispatchInputMiddleware | Create the dispatch-input middleware that reconciles skill projections. |
| skillsDispatchOutputMiddleware | Create the dispatch-output middleware that observes and reconciles skill state. |
| skillsTurnInputMiddleware | Create the turn-input middleware that refreshes and projects loaded skills. |
| skillsTurnOutputMiddleware | Create the turn-output middleware that removes this set's skill projections. |