Pipeline Skills

Bundled Tools

Notation: This document uses ctx.target as shorthand for ctxTarget(ctx) (which returns ctx.envelope.target). Similarly, ctx.target.tool means ctx.envelope.target.run.tool, and ctx.target.config means ctx.envelope.target.locals.config. See the Context specification for the full property paths.

Standard Middleware

All standard middleware operates on ctx.target. Cycle prevention is handled automatically by the runtime's auto-static SCC detection — middleware does not need to declare $inherit: false or $static.

Name	Description
`validate-args`	Validate `ctx.target.args` against the tool's JSON Schema
`validate-allowed-tools`	Validate that the current tool is permitted by the caller's `allowed-tools` constraint. Only checks non-middleware invocations — chain entries are exempt.
`directives`	Parse remark directives from `ctx.target.locals.prompt.expanded`, inject matching tools
`execute`	Call the tool's fn directly on `ctx.target` — the execution leaf
`validate-returns`	Validate `ctx.target.result` against the tool's `returns` JSON Schema
`agent-execute`	Invoke the agent for markdown tools with a prompt

Metadata Middleware

All metadata middleware operates on ctx.target — the context being served. Cycle prevention is handled automatically by the runtime's auto-static SCC detection.

Name	Triggered by	Behavior
`cwd`	`metadata.cwd`	Set `ctx.target.config.cwd` from CLI overrides, metadata value, or globals fallback.
`workspace`	`metadata.workspace`	Set `ctx.target.config.workspace` from CLI overrides or metadata value. Default: `./workspace`.
`paths`	`metadata.paths`	Set `ctx.target.config.paths`, resolving relative to `cwd`. Handles `{ external: "path" }` and `{ ignore: "pattern" }` entries. Calls `ctx.target.manager.refresh()` to re-resolve the current tool against updated paths.
`mcp`	`metadata.mcp`	Lazy-initialize MCP servers (per-server guard), register tools on `globals.tools.programmaticTools`, set `ctx.target.config.mcp`.
`params`	`metadata.params`	Set `ctx.target.tool.params`, defining the tool's argument shape.
`delegate`	`metadata.delegate`	Delegate execution to another tool or inline code. Uses `ctx.target.manager.finish(result)`.
`visibility`	`metadata.visibility`	Set `ctx.target.tool.visibility`.
`returns`	`metadata.returns`	Set `ctx.target.tool.returns`. Passed to agent for structured output.
`model`	`metadata.model`	Set `ctx.target.config.model` (local). Cross-authority propagation handled by `$global` annotation.
`include`	`metadata.include`	Prepend file content to the skill's prompt. Paths resolve relative to the skill file's directory. Runs before directive expansion so directives in included content get processed. Accepts a string (single path) or array of strings.
`frontmatter`	`metadata.frontmatter`	Override frontmatter fields (name, description, params, returns, visibility, allowedTools) via the cascade. Hidden from agents.
`role`	`metadata.role`	Set `ctx.target.tool.role` from metadata.
`tags`	`metadata.tags`	Set `ctx.target.tool.tags` from metadata, normalizing to lowercase-with-hyphens.
`gateway`	`metadata.gateway`	Initialize the gateway for send/receive dispatch. With args: apply overrides to the gateway. Without args: push CLI defaults via `setGateway()` if not already set. Providers (email, Slack) call `setGateway()` to configure their transport before dispatching to skills. The `Gateway` type and `setGateway()` helper are defined in `skills/extensions/gateway/gateway-utils.ts`.
`event`	`metadata.event`	Subscribe skills to event topics via centralized routing config. Also accepts `route:` (singular) — declares the current skill as an event endpoint with ref implicit. Uses `$private: ["$self"]` to stay private automatically.
`domain`	`metadata.domain`	Set `ctx.target.config.domain` from metadata value. Hidden from agents.
`library`	`metadata.library`	Set `ctx.target.config.library` from metadata value or global default. Hidden from agents.
`runtime`	`metadata.runtime`	Set `ctx.target.config.runtime` from metadata value or global default. Hidden from agents.
`log`	`metadata.log`	Configure per-run log settings from cascade metadata: reporter, scope, level. Accepts `{ reporter, scope, level, merge }`. When `merge` is true, adds to global settings instead of replacing. Cleans up run-scoped settings on unwind.
`trust`	`metadata.trust`	Gate tool execution based on trust rules. Prompts for approval via `gateway-receive`. Supports `pathGet` key resolution for per-user trust files.
`allowed-tools`	top-level frontmatter	Not a metadata middleware. `allowed-tools` is a top-level frontmatter field (alongside `name`, `description`, `metadata`), parsed by `extractFrontmatter` at load time and stored on `ctx.run.tool.allowedTools`. Enforcement is handled by `validate-allowed-tools` in the standard pipeline — it checks each non-middleware invocation against the caller's spec. Denied calls throw. Chain entries (internal pipeline mechanics) are exempt.
`observe`	`metadata.observe`	Invoke a callback ref on skill enter/exit/error via `$invoke` hook. Takes `{ ref, depth? }` — `ref` is a callback skill invoked with `{ phase, name, args, result?, error?, contextId }`. Optional `depth` limits observation to N invocation levels deep.
`mock`	`metadata.mock`	Intercept tool calls with mock responses. Activated as `$invoke` hook via `$hook` annotation. Each key in the mock map is a tool name; the value is a skill ref. When the target tool matches, invokes the mock ref instead.
`test`	`metadata.test`	Configure a skill as a test case. Injects standard params and returns, sets visibility hidden. Accepts `{ weight, input }`.
`schedule`	`metadata.schedule`	Initialize the schedule system with optional file persistence and declarative routes. Supports `store` (`file` default, `memory`), `routes` (array of `{ ref, cron?, delay?, at?, timezone?, note? }`). Also accepts `route:` (singular) — declares the current skill as a scheduled endpoint with ref implicit. On startup, reloads persisted entries and rearms timers. Cron entries auto-reschedule after each run. Scheduled tasks fire via `globals.runtime.invoke`. Uses `$private: ["$self"]` to stay private automatically.
`email`	`metadata.email`	Start email listeners and route inbound messages to skills. Flat config with `routes:` array. Also accepts `route:` (singular) — declares the current skill as an email endpoint with ref implicit. Delegates polling to `email-listen-ses` via callback ref. Emits `gateway-message` events when messages arrive. Sets channel via `setGateway()` before dispatch. Uses `$private: ["$self"]` to stay private automatically.
`slack`	`metadata.slack`	Connect to Slack via Socket Mode. Flat config with `routes:` array. Also accepts `route:` (singular) — declares the current skill as a Slack endpoint with ref implicit. Emits `gateway-message` events when messages arrive. Sets channel via `setGateway()` before dispatch. Uses `$private: ["$self"]` to stay private automatically.
`webhook`	`metadata.webhook`	Receive Standard Webhooks. Flat config with `routes:` array. Also accepts `route:` (singular) — declares the current skill as a webhook endpoint with ref implicit. Verifies HMAC signatures and dispatches to skills. Uses `$private: ["$self"]` to stay private automatically.
`roles`	`metadata.roles`	Match identity to role entries via `pathGet` key resolution and glob patterns. Injects all metadata keys as middleware uniformly. Sets `ctx.locals.role`. Uses `$private: ["$self"]` to stay private automatically.
`session`	`metadata.session`	Persist and inject session history across invocations, correlated by a configurable key. Captures args and result by default. Supports in-memory and file-backed storage. Uses `$private: ["$self"]` to stay private automatically.
`state`	`metadata.state`	Configure the state subsystem and optionally inject state values into the prompt. Accepts `include` (key patterns to load), `maxBytes` (budget for injected state), `store` (backend). Uses `$private: ["$self"]` to stay private automatically.
`auth`	`metadata.auth`	Set up auth providers from a `verify` array. Each entry configures a provider for credential verification. Uses `$private: ["$self"]` to stay private automatically.

Directive Middleware

All directive middleware operates on ctx.target. Cycle prevention is handled automatically by the runtime's auto-static SCC detection.

Name	Syntax	Behavior
`arg`	`:arg[name]`	Replace with value from `ctx.target.args`, navigating the target's parent chain.
`skill`	`:skill[name]`	Replace with the skill's description.
`tool`	`:tool[name]`	Alias of `:skill[name]`.
`path`	`:path[rel]`	Resolve relative to skill dir, replace with absolute path.
`eval`	`:eval[expr]`	Evaluate JS expression with `ctx.target` in scope (accessed as `ctx` in the expression).
`env`	`:env[VAR]`	Replace with `process.env[VAR]`.
`context`	`:context[a.b.c]`	Replace with value at dotted path on `ctx.target`.
`config`	`:config[a.b]`	Replace with value at dotted path on `ctx.target.config`.
`script`	`:script[lang]{src=path}`	Embed file as fenced code block.
`inline`	`:inline[path]`	Replace with file contents (no code fences).
`comment`	`<!-- ... -->`	HTML comments are stripped from the prompt before directive processing. Comments inside fenced code blocks are preserved. No directive skill needed — handled by `directives`.

Context Manager

Name Description

context-manager Bridge to framework context operations. Single skill with oneOf schema covering 12 ops: next (advance pipeline), finish (set result and stop), fail (signal failure), abort (cancel pipeline), inject (inject middleware), invoke (tool invocation), refresh (re-resolve tool), get (read property), set (write property), log (emit log event), tail (query recent log events), configure (configure log settings). Primarily used by compiled skills and MCP callers — programmatic code uses ctx.manager.* directly.

Name	Description
`context-manager`	Bridge to framework context operations. Single skill with `oneOf` schema covering 12 ops: `next` (advance pipeline), `finish` (set result and stop), `fail` (signal failure), `abort` (cancel pipeline), `inject` (inject middleware), `invoke` (tool invocation), `refresh` (re-resolve tool), `get` (read property), `set` (write property), `log` (emit log event), `tail` (query recent log events), `configure` (configure log settings). Primarily used by compiled skills and MCP callers — programmatic code uses `ctx.manager.*` directly.

Utility Tools

Name	Description
`file-read`	Read file. Path traversal prevention. Supports line ranges and pattern search with context.
`file-write`	Write file with auto-mkdir. Path traversal prevention. Supports create, append, str_replace, and insert commands.
`file-list`	List directory. Path traversal prevention. Supports recursive depth and glob filtering.
`file-glob`	Find files by glob pattern. Returns `{ totalFiles, truncated, filePaths }`. Supports `maxDepth` for depth limiting and `limit` for result capping. Skips common non-project directories (node_modules, .git, dist, etc.).
`file-search`	Regex search across project files. Returns matches with file paths, line numbers, and content. Supports `include` glob filter, `contextLines`, case sensitivity, and three output modes: `content` (default), `files` (paths with counts), `count` (totals only). Skips binary files.
`web-fetch`	Fetch a URL and extract text content. Converts HTML to clean text (strips nav, scripts, footers). Three modes: `selective` (extract sections matching `searchTerms`), `truncated` (first 8000 chars), `full`. Returns `{ url, title, content, truncated }`.
`shell`	Execute a bash command. Returns `{ stdout, stderr, exitCode }`. Configurable working directory and timeout.
`code`	Evaluate JavaScript code in the current process with `ctx` in scope. Supports `await`.
`help`	Show GNU-style usage documentation for a skill. Without `ref`, shows general usage instructions. With `ref`, shows detailed help for that skill — schema properties formatted as CLI flags with types, defaults, and required markers. Includes fuzzy matching for "did you mean?" suggestions when a skill is not found.
`skill-list`	List available skills. Default: tools that are not hidden. Supports `query` (string, fuzzy name/description search), `tags` filter (array, AND logic), and `includeHidden` (boolean, includes hidden tools). Returns `isExternal` on each entry.
`skill-describe`	Return skill params, description, tags, allowed-tools, source URI, `isExternal` flag, `precedence` (all definitions of this name in resolution priority order), and `authority`.
`invoke`	Dynamically invoke any tool by name. Accepts `ref` (string, required) and `args` (object, optional). Visible to agents and MCP clients as an escape hatch for programmatic tool invocation.
`skill-register`	Register a new skill at runtime from code or markdown source. Hidden from agents.
`skill-unregister`	Remove a dynamically registered skill by ref. Hidden from agents.
`cache-clear`	Clear internal caches. Pass `ref` to clear a single tool, or omit for full wipe.
`event-emit`	Publish an event to a topic. Function handlers fire-and-forget; tool-ref handlers invoke through the pipeline.
`event-subscribe`	Subscribe to a topic. Pass `ref` to invoke a skill on each event, or omit to queue events for `event-wait`.
`event-unsubscribe`	Remove handlers for a topic. Pass `ref` to remove a specific skill handler, or omit to remove all.
`event-wait`	Block until an event arrives on a topic or a timeout expires. Returns accumulated events. Supports named consumer groups and manual acknowledgment.
`event-ack`	Acknowledge or reject events from manual ack mode. Ack removes events from pending. Nack returns them to the front of the queue for reprocessing.
`callback-create`	Create a remote callback endpoint. Returns a `ref` that can be invoked like any skill. The callback queues invocations for a remote client to handle via `callback-wait`/`callback-respond`.
`callback-wait`	Wait for the next pending callback invocation. Returns the invocation ID and args for the remote client to process.
`callback-respond`	Deliver a result to a pending callback invocation, unblocking the caller.
`callback-release`	Release a callback endpoint, cleaning up the programmatic tool and pending state.
`frontmatter`	Override frontmatter fields (name, description, params, returns, visibility, allowedTools) via the cascade. Metadata middleware. Hidden from agents.
`cli-send`	Write a message to stdout. Default channel send transport. Hidden from agents.
`cli-receive`	Read a line from stdin. Default channel receive transport. Hidden from agents.
`gateway-send`	Send a message via the current gateway (dispatches to the transport's send skill). Additional properties are forwarded to the active transport. NOP if no gateway configured.
`gateway-receive`	Receive/elicit a response via the current gateway (dispatches to the transport's receive skill). NOP if no gateway configured.
`trust-grant`	Grant trust for a tool: `always`, `session`, `once`, or `never`.
`trust-revoke`	Revoke trust for a tool.
`trust-list`	List current trust decisions.
`schedule-create`	Schedule a skill invocation for the future. Accepts `delay` string, `at` ISO timestamp, or `cron` expression (mutually exclusive). Supports `timezone` for cron.
`schedule-list`	List pending scheduled tasks.
`schedule-cancel`	Cancel a pending scheduled task by ID.
`email-send`	Send an email via SES. `from` is optional — defaults to the email config when called via `gateway-send`.
`email-receive`	Wait for the next inbound email.
`slack-send`	Post a message to a Slack channel or thread.
`slack-receive`	Wait for the next message in a Slack channel or thread.

Extension Tools (skills/extensions/)

Larger or more opinionated bundled tools. These are always discovered as part of the skills/ search path — extensions/ is purely an organizational subdirectory.

Name	Description
`skill-compile`	Compile a markdown skill to a code skill. Agent-driven with self-verification. Hidden from agents.
`skill-decompile`	Generate markdown skill from a code skill. Hidden from agents.
`skill-test`	Test a tool via mechanical checks and generated unit tests. Hidden from agents.
`skill-clean`	Remove all compiled artifacts. Hidden from agents.
`skill-analyze`	Analyze a skill's runtime environment — cascade metadata, available tools, directives, middleware chain. Traces (executes with instrumentation) and interprets (agent evaluation) by default. Pass `trace: false` and `interpret: false` for static profile only. Hidden from agents.
`skill-revise`	Revise a markdown skill — improve frontmatter, description, and prose. Hidden from agents.
`skill-introspect`	Search bundled framework documentation by keyword query. Hidden from agents.
`skill-baseline`	Run a skill on test inputs and derive testable constraints from the output. Hidden from agents.
`skill-architect`	Generate a project with skills from a natural-language description. Hidden from agents.
`skill-probe`	Probe a skill's pipeline — run the real pipeline with execute and agent-execute replaced by capture functions. Returns the resolved cascade, chain, and execution trace. Runs in a subprocess by default for process isolation. Hidden from agents.
`skill-doctor`	Diagnose the Agent Apps installation, project configuration, dependencies, AWS access, and skills health. Reports structured findings with severity levels. Pass `fix: true` to auto-repair issues.
`tutor`	Interactive learning lessons for Agent Apps — slides, quizzes, and animations. Lessons are generated on demand, cached to disk, and tracked in a library.
`init`	Scaffold a new Agent Apps project. Hidden from agents.
`update`	Update the agent-apps CLI to the latest release. Hidden from agents.
`hub-search`	Search the hub for skill packages. Scored keyword + optional semantic search. Hidden; agents access via `allowed-tools`.
`hub-add`	Install a skill package with dependency resolution, integrity verification, and per-package npm install. Supports `name@range` and `dryRun`. Hidden.
`hub-remove`	Remove an installed hub package. Warns about reverse dependencies. Hidden.
`hub-update`	Update installed hub packages to latest. Re-resolves dependencies, runs per-package npm install. Hidden.
`hub-list`	List installed hub packages with available updates and dependency tree. Hidden.
`hub-info`	Show detailed package info: all versions, frontmatter, dependencies, installed status. Hidden.
`hub-publish`	Publish a skill to the hub. Validates, extracts frontmatter, computes integrity, pushes PR branch. Hidden.
`web`	HTTP server with route-based skill dispatch. Routes are declared in the `web` middleware's `routes:` config. Also accepts `route:` (singular) — declares the current skill as a web endpoint with ref implicit. Metadata middleware. Hidden from agents.
`web-send`	Directly control the HTTP response — set status, headers, body, redirect, write body chunks, or end. For streaming and custom responses.
`web-receive`	Read from the HTTP request — body, query params, headers. Hidden from agents.
`websocket`	WebSocket server with socket-based skill dispatch. Routes are declared in the `websocket` middleware's `routes:` config. Also accepts `route:` (singular) — declares the current skill as a websocket endpoint with ref implicit. Metadata middleware. Hidden from agents.
`websocket-send`	Send a message to all clients on a WebSocket socket.
`websocket-receive`	Wait for the next message on a WebSocket socket.
`deploy`	Propagate deploy config defaults to `target.locals.config.deploy`. Metadata middleware. Hidden from agents.
`deploy-app`	Build and deploy the current project. Resolves provider from keyed config. Hidden from agents.
`deploy-list`	List active deployments. Hidden from agents.
`deploy-status`	Show deployment status. Hidden from agents.
`deploy-logs`	Fetch deployment logs. Hidden from agents.
`deploy-remove`	Remove a deployment. Hidden from agents.
`sandbox`	Propagate sandbox config defaults (engine, constraints) to `target.locals.config.sandbox`. Metadata middleware. Hidden from agents.
`sandbox-app`	Run the current project in a sandboxed container. Hidden from agents.
`sandbox-build`	Build a sandbox image for the project. Hidden from agents.
`sandbox-list`	List running sandbox containers. Hidden from agents.
`sandbox-status`	Show sandbox container status. Hidden from agents.
`sandbox-stop`	Stop a running sandbox container. Hidden from agents.
`roles`	Identity-based cascade merging. Matches identity via `pathGet`, injects all metadata keys as middleware. Metadata middleware. Hidden from agents.
`roles-list`	List configured role entries and their match patterns.
`agent`	Agent policy layer — discovers tools, builds the `invoke` tool, creates hook callback refs, captures agent trace to `target.locals.agent.trace`, emits progress events, calls agent provider.
`agent-context`	Standard context block prepended to agent prompts via the `include` middleware. Provides channel description. Hidden from agents.
`agent-async-guide`	Async patterns reference (timers, Promise.all, fire-and-forget, polling alternatives) injected into agent prompts for workflow skills via `role: context`. Hidden from agents.
`agent-strands`	Strands-based LLM loop using Amazon Bedrock. Default agent provider. Supports opt-in `context-edit` (via `config.contextEdit: true`) — allows the agent to edit its own conversation context to manage long sessions. Context-edit supports regex and range matching for precise edits, occurrence-based targeting, and automatic cleanup of stale entries.
`agent-kiro`	Kiro ACP-based LLM loop. Alternative provider using Kiro CLI as the backend. Tools served via in-process HTTP MCP server.
`email-listen-ses`	Own the SES/S3 email polling lifecycle. Polls S3 for inbound email, parses MIME, invokes a callback ref for each message. Returns a stop callback ref for cleanup. Hidden from agents.
`email-setup`	Set up email infrastructure for the configured provider. Creates SES resources (receipt rules, S3 bucket policies) needed for inbound email.
`session`	Persist and inject session history across invocations, correlated by a configurable key. Metadata middleware. Hidden from agents.
`session-history`	Directive: replace `:session-history[]` with formatted session history. Hidden from agents.
`mcp-server`	Expose project skills as an MCP server over stdio or HTTP. Supports `transport` (stdio\|http), `port`, `allowedTools`, and `heartbeat` args. Any Agent Apps project becomes an MCP tool provider. Hidden from agents.
`repl`	Interactive agent session with event-driven rendering (streaming, spinner, tool call display) and slash commands.
`debug`	Pipeline debugger — observe invocations, set breakpoints, step through execution. Invokable directly for control (breakpoints, continue, step, inspect). Hidden from agents.
`profile`	Pipeline profiler — collect timing data for every invocation and chain entry. Invokable directly for reports. Hidden from agents.
`skill-debug`	Debug a skill — run it with pipeline tracing and optional auto-continuing breakpoints. CLI wrapper around `debug`. Hidden from agents.
`skill-profile`	Profile a skill — run it with timing collection and return a formatted report. CLI wrapper around `profile`. Hidden from agents.
`state-get`	Read a value from persistent state by key. Returns null if not found. Supports `file` (default, persists to disk) and `memory` (process-lifetime) backends.
`state-set`	Write a value to persistent state by key. Supports `file` and `memory` backends. Notifies `state-wait` listeners on write.
`state-delete`	Delete a value from persistent state by key. Supports `file` and `memory` backends.
`state-list`	List all keys in persistent state, optionally filtered by prefix. Supports `file` and `memory` backends.
`state-wait`	Wait for a state key to be set. Returns immediately if the key already exists, otherwise blocks until `state-set` writes it or the timeout expires. Supports `file` and `memory` backends.

The following sections describe each extension tool in detail.