--- title: "Skills, Capsules, and Portable AI Capabilities" slug: "capsule-skills-portable-capabilities" summary: "How the Capsule protocol adopted the Agent Skills ecosystem to make AI work artifacts universally accessible — and how skills embedded in capsules create a new class of verifiable, portable capabilities." status: "draft" version: "1.0" date: "2026-03-21" updated: "2026-05-01" audience: - "partners" - "investors" - "technical adopters" - "developers" tags: - "capsule" - "skills" - "agent-skills" - "interoperability" - "portability" - "orchestration" canonical_path: "/research/capsule-skills-portable-capabilities" --- # Skills, Capsules, and Portable AI Capabilities ## How the Agent Skills Ecosystem Makes Capsules Universal — and How Capsules Make Skills Verifiable ## Abstract AI agents are proliferating across platforms, but they remain isolated. Each agent ecosystem defines its own way to describe capabilities, package tools, and communicate instructions. Work produced in one system cannot easily be understood, verified, or continued in another. The Capsule protocol addresses this by packaging AI work — content, state, history, and executable capabilities — into portable, verifiable containers. But portability requires more than a good file format. It requires that the capabilities embedded in a capsule are legible to any agent that opens it. This paper describes how the Capsule protocol adopted the Agent Skills specification — an open standard for teaching AI agents new capabilities — as its native format for embedded skills. It explains why this decision was made, what it enables architecturally, and how the combination of skills and capsules creates a class of artifacts that are simultaneously portable, self-executing, and auditable. It also introduces the capsule skill: a general-purpose skill that teaches any AI agent to understand the capsule protocol itself, enabling capsule literacy across the entire Agent Skills ecosystem without requiring custom integrations. --- ## 1. The Problem: Capabilities That Cannot Travel The first versions of the Capsule protocol embedded executable capabilities as custom tools — Python scripts registered in a `tools/tools.json` file with explicit function signatures, entrypoints, and sandbox constraints. This worked for capsule-aware systems but created an immediate limitation: no agent outside the capsule ecosystem recognized the format. A capsule containing a compliance screening tool could execute in an environment that understood `tools.json`, but if that same capsule was handed to a foundation model, a different orchestration framework, or an agent built on a different platform, the tools were opaque. The receiving system would need capsule-specific code to discover, interpret, and invoke them. This is the capability portability problem. A work artifact can only orchestrate its own execution if the agent receiving it can understand the capabilities the artifact carries. Custom formats restrict the artifact to a closed ecosystem. Open formats unlock it. --- ## 2. The Agent Skills Specification The Agent Skills specification, developed as an open standard and adopted by over thirty agent products, provides a simple, portable format for teaching AI agents new capabilities. A skill is a directory containing a SKILL.md file — YAML frontmatter describing the skill's name, purpose, and metadata, followed by markdown instructions explaining when and how to use it. Skills can optionally include executable scripts, reference documentation, and supporting assets. The format follows a progressive disclosure model. An agent first reads the skill catalog (names and descriptions) to understand what's available. When a skill is needed, the agent reads the full SKILL.md instructions. If the skill references scripts or reference material, the agent loads those on demand. This matches how both humans and AI systems naturally approach unfamiliar capabilities: understand the landscape, then go deep where needed. The specification has been adopted by Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, OpenAI Codex, Goose, Junie, Amp, Roo Code, Databricks, and others. This breadth of adoption means a skill written once is legible to a wide range of agent products without modification. --- ## 3. Why Capsules Adopted Skills The decision to replace the custom tools format with Agent Skills was driven by three considerations. ### Interoperability Without Integration A capsule carrying skills in the Agent Skills format is immediately legible to any skills-compatible agent. The agent does not need to know what a capsule is — it simply discovers a SKILL.md file and follows the instructions. This transforms the question from "does this agent support capsules?" to "does this agent support skills?" The latter has a much broader affirmative answer. ### Simpler Authoring The custom `tools.json` format required explicit function signatures, parameter schemas, entrypoint declarations, and sandbox specifications. Skills replace this with natural language instructions in markdown. An agent reads the instructions and follows them, consulting scripts and reference material as directed. This is both easier to author and more resilient to variation in how different agents execute code. ### Ecosystem Alignment Building on an emerging standard rather than maintaining a proprietary format reduces adoption friction. Organizations evaluating capsules do not need to learn a capsule-specific tool format. Teams already using skills in their agent workflows find that capsules integrate naturally. As the skills ecosystem evolves — new agent products, validation tools, skill registries — capsules benefit without additional work. The trade-off is that skills use natural language instructions rather than formal function signatures. Capsule v0.6 compensates at the artifact boundary rather than by changing the skill format: the manifest records content hashes and `skill_trust` entries, while the chain can record which host actions used which skill context. Input/output schemas and determinism declarations are useful host policy or future manifest extensions, not core v0.6 fields. --- ## 4. How Skills Work Inside Capsules A capsule's skills live in a `skills/` directory. Each skill is a subdirectory containing a SKILL.md file and optional supporting resources. The capsule manifest registers embedded content and skill trust metadata that the skills specification alone does not provide. In v0.6, the manifest's `content_index` can commit to the bytes of a bundled skill directory, and `skill_trust` can record the issuer and trust decision for a skill. It does not yet declare formal input/output schemas or determinism levels. When a capsule's plan references a skill, the execution flow proceeds through discovery, validation, loading, execution, and optional recording. The executor verifies the packaged bytes against the manifest content index, loads the instructions, follows them through the host's policy, and can append a chain event describing the invocation, inputs, outputs, result hashes, and completion status. This event recording is the critical addition capsules bring to skills. In a standalone agent environment, a skill executes and produces a result. Inside a capsule, the host can preserve a tamper-evident record that links the result to the packaged skill bytes, input data, and prior chain state. The skill is portable; the audit trail belongs to the capsule. --- ## 5. What Capsules Add to Skills The skills specification provides a format for portable capabilities. Capsules add four properties that skills alone do not have. ### Integrity Verification Every skill file inside a capsule is covered by the package hash. The manifest records per-skill SHA-256 hashes that the executor verifies before invocation. On signed capsules, the package signature covers all skill files. Modifying a skill after packaging invalidates the capsule's integrity, making tampering detectable. ### Determinism Contracts The manifest declares whether a skill is deterministic, bounded, or probabilistic. Deterministic skills must produce byte-identical output given the same input — enabling verification through re-execution. Bounded skills must produce structurally equivalent output conforming to a declared schema. Probabilistic skills record their output without deterministic guarantees. These contracts give consuming systems a basis for deciding how much to trust a skill's results. ### Audit Trails Every skill invocation is recorded in the capsule's event chain as a mutation event. The record includes the skill name, the plan node that triggered it, the parameters provided, a hash of the result, execution timing, and completion status. This chain is append-only and hash-linked, providing a verifiable history of every capability execution. ### Orchestration Context Skills inside a capsule are not invoked in isolation — they execute as part of a structured plan with declared dependencies, capability gates, and output contracts. The orchestration layer determines when a skill can run (based on predecessor completion and capability grants), what data it receives (from prior skill results or resolved resources), and what contract its output must satisfy. This structured context is absent when a skill runs standalone. --- ## 6. The Capsule Skill: Teaching Agents About Capsules A particularly significant application of the skills model is the capsule skill itself — a general-purpose skill that teaches any AI agent to understand the capsule protocol. Rather than requiring each agent platform to build native capsule support, the capsule skill provides the instructions an agent needs to open a .capsule file, read the manifest to understand the objective, interpret the state snapshot and handoff document, discover embedded skills, follow the plan, record events, and produce updated capsules. The skill does not modify the agent — it instructs it. Any agent that can read a SKILL.md file and follow instructions gains capsule literacy. This approach treats the capsule protocol itself as a learnable capability rather than a required integration. The distribution mechanism is the same Agent Skills ecosystem that capsules already use for embedded capabilities. An agent that has the capsule skill installed can receive a capsule from any source — another user, another organization, another AI system — and work with it natively. ### The Bootstrapping Dynamic This creates a recursive quality that is central to the capsule vision. The Agent Skills ecosystem provides the format for portable capabilities. The capsule skill uses that format to teach agents about capsules. Capsules use that same format to carry capabilities inside themselves. The skills ecosystem becomes both the medium through which capsules gain interoperability and the format through which capsules deliver value. A user working with a frontier model installs the capsule skill. The model can now open capsules, discover the skills embedded inside them, and execute the work. The embedded skills may reference other capsules through delegation. Those child capsules carry their own skills. At every level, the same format — the same SKILL.md convention — provides the bridge between the agent and the work. --- ## 7. Skill Security and Trust Embedded code introduces execution risk that inert data does not carry. The capsule protocol addresses this through a layered security model. Hash verification ensures that every skill file matches its declared hash in the manifest and content index. Tampering after packaging is detectable. On signed capsules, the package signature binds all skill files to the signer's identity, providing attribution. Capability gating requires that skill execution be explicitly authorized — a skill cannot run unless the relevant capability has been granted through a chain event. Sandbox constraints declared in the skill's metadata specify what environment access the skill requires, and conforming runtimes must not grant more than declared. For capsules from untrusted sources, runtimes may require human approval before executing embedded code. This aligns with the Agent Skills specification's trust considerations for project-level skills and with the capsule protocol's authorship model, where the human serves as the guide and approval authority. The principle is: declare, review, grant, execute, record. Nothing runs silently. --- ## 8. Skills and the Capsule Maturity Model The adoption of skills maps directly to the capsule maturity model, which measures work continuity across boundaries. At Levels 0 through 2, capsules function as static, auditable, and executable artifacts. They carry content, event chains, and declared intent — but they depend on the consuming agent to provide all capabilities externally. At Level 3, capsules become continuable — structured handoffs and state snapshots allow seamless transfer between actors. Skills are not strictly required at this level, but the handoff context benefits from knowing what capabilities are available. Level 4 is where skills become essential. An orchestrable capsule carries the skills it needs to execute its own plan. An agent opening a Level 4 capsule does not need external tools, API credentials, or ambient knowledge. The capsule is the complete package. This level represents the current protocol version. Level 5, targeted for a future release, adds federated trust — cross-organization verification, encryption, and hosted discovery. At this level, skills embedded in capsules carry not just instructions and integrity hashes but verifiable provenance about who created the skill and under what authority. --- ## 9. Design Decisions and Trade-offs Several design choices shaped how skills integrate with capsules. ### Skills Are Unchanged From the Ecosystem Standard Capsule-embedded skills use the Agent Skills format without modification. Capsule-specific metadata such as content hashes and `skill_trust` entries lives in the manifest, not in the SKILL.md files. This means a skill extracted from a capsule works identically in any other skills-compatible environment. Portability is preserved in both directions: skills move freely into capsules and freely out of them. ### The Manifest Is the Governance Bridge The capsule manifest serves as the bridge between the ecosystem-standard skill format and the capsule's governance model. The skill provides the capability; the manifest commits to the packaged bytes and records trust metadata. Richer schema contracts and determinism guarantees can be layered by hosts or future protocol revisions. This separation allows the skill format to evolve independently of capsule governance, and vice versa. ### No Backward Compatibility With the Custom Tools Format The migration from `tools/tools.json` to Agent Skills was a clean break. Existing capsules using the old format require migration. This was a deliberate choice — maintaining two formats would add complexity for every future implementer, and the custom format had no adoption outside capsules. A clean migration preserves simplicity for the ecosystem that matters. --- ## 10. Implications The combination of skills and capsules has several implications for how AI-mediated work evolves. ### Universal Capsule Access Any AI agent that supports the Agent Skills specification can be taught to work with capsules through a single skill installation. This removes the requirement for platform-specific integrations and lowers the barrier to capsule adoption across the AI ecosystem. ### Verifiable AI Capabilities Skills embedded in capsules gain properties they do not have standalone: package integrity, explicit trust metadata, and a place to record execution evidence in the event chain. Organizations that need to demonstrate what an AI did, how it did it, and with what tools gain a concrete mechanism for preserving that evidence. ### Portable Workflows A capsule template carrying embedded skills, a structured plan, and output contracts can be distributed to any organization. The receiving party instantiates the template, and any skills-compatible agent can execute the workflow — producing results that are verifiable against the template's contracts. The workflow travels with the artifact. ### Local and Private Execution Because skills are embedded in the capsule rather than hosted externally, execution can happen entirely locally. A local language model with the capsule skill can open, execute, and seal capsules without any network access. This enables private, offline workflows for sensitive data — compliance screening, medical assessments, legal review — while maintaining the full audit trail. --- ## 11. Current Status and Next Steps The skills integration is implemented in the capsule SDK. Capsules can be built with embedded skills, and the plan runner can discover, verify, and execute them with full event recording. The capsule skill — the general-purpose skill that teaches agents about the protocol — is now public as version 0.3.0. It bundles the JavaScript SDK, protocol instructions, helper scripts, and local-model guidance so skills-compatible agents can read, verify, continue, and create `.capsule` files without a native capsule integration. Near-term work focuses on cross-runtime verification (the same capsule executed by different agents producing consistent results), trust infrastructure for signed skills (verifiable attribution for skill authors), expanded test coverage for the skill execution and delegation lifecycle, and the connected-capsules bridge needed for high-volume multi-actor experiments. The broader direction is toward an ecosystem where capsules and skills reinforce each other: skills make capsules accessible, capsules make skills verifiable, and together they provide a foundation for AI work that is portable, auditable, and trustworthy across organizational and platform boundaries.