Proposal: Executable Agent Skills

## Summary

Current Agent Skills excel at **instruction**, but they lack a native **execution model**. This forces users (or agents) to manually manage environments, dependencies, and runtime safety—creating friction, security risks, and reproducibility failures.

This proposal introduces a **minimal, optional extension** to the `SKILL.md` frontmatter that enables **secure, containerized, reproducible execution** of skills—without breaking existing skills or changing the authoring model.

The design is intentionally small: four execution fields plus schemas. Together, they transform a skill from a *README an agent follows* into a *capability an agent can execute*.

> **Skills tell the Agent what to do.**
> **Executable manifests let the Agent actually do it.**

---

## The Gap: The "Instruction-Only" Problem

Today, skills stop at instruction. Execution is delegated to the user.

### Resulting Issues

1. **Dependency Hell:** Users must manually install packages (`pip`, `npm`, `cargo`) matching the skill's requirements.
2. **Environment Pollution:** Global dependencies conflict across different skills.
3. **No Isolation:** Scripts run on the host machine, risking accidental damage (`rm -rf`) or data leakage.
4. **Non-Reproducibility:** OS differences and version drift cause "works on my machine" failures.
5. **No Contracts:** Inputs and outputs are undocumented and unvalidated, leading to hallucinated arguments.

---

## The Solution: Executable Manifests

We extend the `SKILL.md` frontmatter with **optional execution fields**.

### Proposed Frontmatter Extension

```yaml
---
name: pdf-extract
description: Extract text from PDF files using OCR or text layers.

# EXECUTION FIELDS (OPTIONAL)
from: python:3.12-slim
build: pip install pypdf pdfplumber
command: python /work/extract.py ${file}

inputSchema:
type: object
properties:
file:
type: string
description: Path to PDF file
required: [file]

outputSchema:
type: object
properties:
text:
type: string
---

```

If these fields are present, the skill is executable. If not, the skill behaves exactly as it does today (pure documentation).

### Field Definitions

| Field | Purpose | Why It Matters |
| --- | --- | --- |
| `from` | Container base image | Guarantees identical runtime everywhere. |
| `build` | One-time setup (cached) | Automates dependency installation. |
| `command` | Deterministic entrypoint | Defines explicit execution behavior. |
| `inputSchema` | JSON Schema validation | Prevents hallucinated inputs *before* execution. |
| `outputSchema` | JSON Schema validation | Enables reliable output parsing and chaining. |

This is the **smallest useful surface area** that unlocks reliable execution.

---

## Workflow: Before vs. After

### Current State

**User:** "Extract text from report.pdf"
**Agent:**

1. Reads README.
2. Asks user to install `pypdf`.
3. Writes a Python script to a temporary file.
4. Asks user to run the script.
**Result:** High friction, low safety, zero reproducibility.

### Proposed State

**User:** "Extract text from report.pdf"
**Agent:**

1. Identifies `pdf-extract` skill.
2. Validates input against `inputSchema`.
3. Executes skill in a sandbox.
4. Returns structured output.
**Result:** Zero friction, high safety, guaranteed reproducibility.

---

## Technical Architecture

The execution engine acts as a translation layer between the Agent and the Docker runtime.

```mermaid
graph TD
A[Agent / User] -->|1. Invoke with Args| B(Execution Engine)
B -->|2. Validate Input| C{Schema Valid?}
C -->|No| D[Return Error]
C -->|Yes| E[Build/Load Container]
E -->|3. Execute Command| F[Sandboxed Runtime]
F -->|4. Capture Output| B
B -->|5. Return Structured Data| A

```

### Security Model

* **Isolation:** Ephemeral containers per execution. No host filesystem access (except explicitly mounted inputs).
* **Networking:** Disabled by default unless explicitly requested.
* **Validation:** All arguments are validated against the schema *before* the container starts.
* **Secrets:** Injected at runtime via environment variables; never written to disk or logs.

---

## Reference Implementation: Enact

[Enact](https://github.com/EnactProtocol/enact) is a working, open-source implementation of this proposal. It proves that combining documentation and execution in one file is viable.

### 1. Discovery (`enact learn`)

The "Literate" aspect: Agents can inspect the contract before execution. This reveals the manifest, schema, and human-readable documentation in one view.

```bash
$ enact learn enact/hello-python

enact/hello-python@1.0.3
───────────────────────────

---
name: "enact/hello-python"
version: "1.0.3"
description: "A simple Python greeting tool"
from: "python:3.12-slim"

inputSchema:
type: object
properties:
name:
type: string
description: "Name to greet"
default: "World"

command: "python /work/hello.py ${name}"
---

# Hello Python

A simple Python tool that greets you by name.

```

### 2. Execution (`enact run`)

Once validated, the tool is executed in a secure, ephemeral container.

```bash
$ enact run enact/hello-python --args '{"name": "Anthropic"}'

◇ ✓ Resolved: enact/hello-python
◐ Running enact/hello-python (python:3.12-slim)...
◇ ✓ Execution complete

Hello, Anthropic! 🐍
Generated at: 2025-12-19T15:33:38
Python version: 3.12.12

```

*Note: This proposal does **not** require adopting Enact itself—only the manifest semantics it effectively demonstrates.*

---

## Backwards Compatibility

* All execution fields are **optional**.
* Existing skills continue to work unchanged.
* No migration is required.
* Instruction-only skills remain first-class citizens.

## Closing

This proposal does not change what skills *are*. It changes what skills can **do**.

By adopting a minimal executable manifest, Agent Skills evolve from static documentation into **real, composable, secure capabilities**.

**One file becomes a portable, executable unit of intelligence.**