Agent Actions Specification

Version: 0.1.1 (DRAFT)

1. Overview

This specification extends Agent Skills by introducing ACTIONS.yaml. It transforms documentation-only skills into runnable, typed tools with execution semantics.

The Progression

This spec supports a gradual adoption path for tool builders:

1. Start simple
   └── SKILL.md only (document your scripts)

2. Add execution
   └── SKILL.md + ACTIONS.yaml (typed inputs, direct execution)

3. Add portability
   └── SKILL.md + ACTIONS.yaml + Containerfile (containerized)

4. Share publicly
   └── Publish to registry

2. Quick Start

Directory Layout:

mendable/firecrawl/
├── SKILL.md      # Agent-facing docs
├── ACTIONS.yaml  # Execution config
└── main.py       # Implementation

ACTIONS.yaml:

env:
  API_KEY: { secret: true, required: true }

actions:
  - name: scrape
    description: Scrape a URL to markdown
    command: ["python", "main.py", "scrape", "{{url}}"]
    inputSchema:
      type: object
      required: [url]
      properties:
        url: { type: string }
    outputSchema:
      type: object
      properties:
        content: { type: string }

3. Schema Reference

Top-Level Fields

Field	Type	Description
env	Map	Environment variables/secrets configuration.
actions	Array	List of executable action definitions.
build	String/Array	Setup commands (e.g., pip install). Runs once per environment.

Environment Object

Property	Description
secret	bool (Default: false). If true, value is masked in logs.
required	bool (Default: false). Execution fails if missing.

Action Object (MCP-Compatible)

Field	Type	Required	Description
name	string	Yes	Unique identifier.
command	string or array	Yes	Execution command with optional {{var}} templates.
inputSchema	object	Yes	JSON Schema for parameters.
outputSchema	object	No	JSON Schema for stdout.

4. Execution Semantics

Command Syntax

• String Form: command: python main.py (No templates allowed).
• Array Form: command: ["python", "main.py", "{{url}}"] (Required for templates).
• Substitution: {{var}} is replaced by the literal value as a single argument. No shell interpolation.

See Command Syntax for template substitution rules and default handling.

Runtime Modes

1. Containerized (Recommended): Executed inside a container if Containerfile exists.
2. Local: Executed on host. Clients must warn users due to lack of sandboxing.

See Execution Modes for details on containerization and build steps.

Security

Secrets defined in env with secret: true are injected at runtime via environment variables. The LLM never sees the secret, only the instruction to run the action.

See Security for threat model and best practices.

5. Composability & Usage

Because actions output structured JSON to stdout, they compose naturally with standard Unix tools or other actions.

Example: Piping Output Execute an action and filter the specific metadata field using jq:

# Run action -> Pipe JSON output -> Filter
client run mendable/firecrawl/scrape '{"url": "https://example.com"}' | jq -r '.metadata.title'

Example: Chaining Pass the output of one action into another (pseudo-code):

# Scrape a URL -> Summarize the content
content=$(client run firecrawl/scrape '{"url": "..."}' | jq -r '.content')
client run openai/summarize --args "{\"text\": \"$content\"}"

6. Comparison

Capability	SKILL.md Only	+ ACTIONS.yaml
Type	Documentation	Executable Tool
Inputs	Prose (ambiguous)	Typed JSON Schema
Secrets	Exposed in context	Injected at runtime
Pipeline Ready	No	Yes (JSON Stdout)

Further Reading

• Command Syntax - Template substitution and default handling
• Execution Modes - Containerized vs local execution
• Security - Secret management and threat model
• MCP Integration - How actions map to MCP tools
• Examples - Full examples including complex CLIs