Agent Actions
Typed, executable actions for agent skills
with secure secrets and MCP compatibility.
Add execution semantics to your skills: typed inputs, validated outputs, and secrets that never touch the LLM. Turn documentation into runnable, composable tools.
# Environment variables injected at runtime
env:
API_KEY: { secret: true, required: true }
# List of executable actions
actions:
- name: scrape # Action identifier
description: Scrape a URL to markdown # Shown to agents
command: python scripts/main.py scrape {{url}}
inputSchema: # JSON Schema for inputs
type: object
required: [url]
properties:
url: { type: string }
outputSchema: # JSON Schema for outputs
type: object
properties:
content: { type: string }Why ACTIONS.yaml?
SKILL.md files bundle scripts, but there's no standard way to define typed inputs, execute without parsing prose, or inject secrets securely.
ACTIONS.yaml fills this gap—add execution semantics to skills while remaining fully backwards-compatible. Skills without it continue to work unchanged.
Typed Inputs & Outputs
Define JSON Schema for parameters and return values. No more parsing prose instructions or guessing argument formats.
Secure Secrets
Secrets are injected at runtime via environment variables. The LLM never sees the secret—only the instruction to run the action.
Direct Execution
Invoke actions directly with validated inputs. No need to load full skill context—actions expose precise, context-efficient interfaces.
Pipeline Ready
Actions output structured JSON to stdout. Compose naturally with Unix tools, other actions, or as MCP tools.
MCP Compatible
Actions align with MCP tools—same schema structure, same invocation pattern. Expose actions as MCP tools immediately.
SKILL.md Compatible
ACTIONS.yaml enhances existing skills. Skills without it continue to work unchanged—it's fully backwards-compatible.
SKILL.md vs SKILL.md + ACTIONS.yaml
ACTIONS.yaml enhances skills with typed execution—existing skills work unchanged
Works with your favorite AI tools
ACTIONS.yaml-enhanced skills work with AI coding agents, automation platforms, and MCP servers
Registries
Discover and publish ACTIONS.yaml-enhanced skills
Examples
Real-world ACTIONS.yaml files from the community
env:
PDF_PASSWORD: { secret: true }
actions:
- name: extract
description: Extract text and metadata from PDF files
command: python extract.py {{file_path}}
inputSchema:
type: object
required: [file_path]
properties:
file_path:
type: string
description: Path to the PDF file
outputSchema:
type: object
properties:
text: { type: string }
page_count: { type: integer }env:
VIEWPORT_WIDTH:
description: Browser viewport width
default: "1280"
actions:
- name: capture
description: Capture screenshots of web pages
command: npx playwright screenshot {{url}} screenshot.png
inputSchema:
type: object
required: [url]
properties:
url:
type: string
format: uri
description: URL to captureHow to use ACTIONS.yaml
Start with SKILL.md
Create a SKILL.md file that documents your scripts. This works standalone for agent-facing documentation.
Add ACTIONS.yaml
Create an ACTIONS.yaml file alongside your SKILL.md. Define environment variables and your list of actions.
Define action schemas
Specify inputSchema and outputSchema using JSON Schema. Agents use this for validation and structured output.
Write your command
Use string or array form with {{var}} templates. Variables are replaced with validated input values at runtime.
Mark secrets
Set secret: true for sensitive environment variables. Clients handle secure storage—the LLM never sees the value.
Invoke actions
Run actions directly with validated inputs. Compose outputs with Unix tools, other actions, or expose as MCP tools.
Skill folder structure
Add ACTIONS.yaml alongside your SKILL.md to enable typed execution:
my-skill/
├── SKILL.md # Agent-facing docs (required)
├── ACTIONS.yaml # Execution config (this spec)
└── scripts/
└── main.py # Implementation# Run an action directly
$ client run my-skill:scrape '{"url": "https://example.com"}'
◐ Validating input schema...
◇ ✓ Input valid
◐ Running: python scripts/main.py scrape https://example.com
◇ ✓ Execution complete
{"content": "# Example Domain\n\nThis domain is for use in..."}FAQ
How does ACTIONS.yaml relate to SKILL.md?
ACTIONS.yaml enhances SKILL.md by adding typed, executable actions. Skills without ACTIONS.yaml continue to work unchanged—it's fully backwards-compatible.
Can I use my existing SKILL.md files?
Yes! SKILL.md files work as-is. ACTIONS.yaml is optional—add it when you want direct execution with typed inputs and outputs.
Why typed inputs and outputs?
Typed schemas enable validation before execution, structured output parsing, and precise interfaces. Agents don't need to interpret prose or guess argument formats.
How do secrets work?
Define secrets in env with secret: true. Secrets are injected as environment variables at runtime. The LLM never sees the secret value—only the action name.
What is the command syntax?
Use string form (shell-parsed with templates) or array form (explicit argument boundaries). Variables like {{url}} are replaced with validated input values.
How does this work with MCP?
Actions align with MCP tools—same schema structure, same invocation pattern. Actions can be immediately exposed as MCP tools with no changes needed.
What are the required fields?
For actions: name, description, command, and inputSchema are required. Environment variables and outputSchema are optional but recommended.
Is ACTIONS.yaml an open standard?
Yes! The specification is open source. We welcome contributions and feedback via GitHub and Discord.