Agent Skills

Agent

The agent is split into two tools:

  • agent — Policy layer. Discovers available tools via a shared filter (resolveVisibleTools), builds the invoke tool (code execution through the pipeline), creates serializable callback refs for invocation and lifecycle hooks, captures the agent trace to target.locals.agent.trace, enforces structured returns, emits progress events when events arg is set, and delegates to the agent provider.
  • agent-strands — LLM loop. The bundled Strands/Bedrock implementation lives in skills/extensions/agent/strands/. Supports opt-in context-edit (via config.contextEdit) for managing long conversation contexts. An alternative Kiro ACP-based implementation (agent-kiro) is in skills/extensions/agent/kiro/.

The agent communicates with its provider via fully serializable callback refs (invokeRef and hookRef), created via createCallbackRef. This means the agent interface works over MCP and across process boundaries — no functions cross the serialization boundary.

To use a different LLM provider, create your own agent provider skill and configure it via model.agent in the cascade metadata, or shadow agent-strands by placing a replacement earlier in the search path. The agent policy layer stays unchanged. See the Agent Specification for the interface contract.

MCP Server

Expose your project's skills as an MCP server over stdio or HTTP. Any Agent Apps project becomes an MCP tool provider for Claude Desktop, Cursor, or other MCP-compatible clients.

agent-apps mcp-server                                    # stdio (default)
agent-apps mcp-server --transport http --port 8080  # HTTP

Arguments:

  • transport — stdio (default) or http
  • port — port for HTTP transport (default 8080, ignored for stdio)
  • allowedTools — glob patterns to scope exposed tools
  • heartbeat — send periodic progress notifications to prevent client timeouts (default true)

This is the inverse of MCP bridging (the mcp metadata key). Combined, you get bidirectional MCP: consume external tools AND expose your own.

REPL

Interactive agent session with event-driven rendering (streaming markdown-to-ANSI), persistent readline with history and tab completion, and slash commands (/help, /clear, /history, /debug, /exit). Ctrl-C cancels the current agent turn; double-tap to exit. Shows elapsed time after each turn.

agent-apps repl
agent-apps repl --task "Summarize my tasks"   # Start with an initial task

Agent Context

Standard context block prepended to all agent prompts via the include middleware in default.skill.md. Provides:

  • Channel description (CLI, Slack, email, etc.)

Hidden from agents — it's injected into the system prompt, not exposed as a callable tool.

Include

Metadata middleware that prepends file content to the skill's prompt before directive expansion. Paths resolve relative to the skill file's directory. Useful for shared context (style guides, data schemas, rules) that should apply to multiple skills.

# Single include
metadata:
  include: shared-context
# Multiple includes
metadata:
  include:
    - style-guide
    - data-schema

The default.skill.md declares $merge: { include: append } so child includes are added after parent includes. The default include value references the agent-context prompt file, providing standard agent context to all skills.

Ask AI