ENACT.md
Executable AI tool definitions with containerized execution
and semantic versioning.
Think of ENACT.md as a SKILL.md that can actually run: a portable, verified format for defining AI tools that execute in isolated containers with full reproducibility.
---
name: enact/firecrawl
version: 1.1.0
description: Scrape, crawl, and extract data from websites
# Containerized execution
from: python:3.12-slim
build: pip install requests
command: python firecrawl.py ${action} ${url}
# Environment & secrets
env:
FIRECRAWL_API_KEY:
secret: true
# MCP-compatible schema
inputSchema:
type: object
properties:
action:
type: string
enum: [scrape, crawl, extract]
url:
type: string
---
# Firecrawl
Web scraping that just works. No curl escaping,
no dependency issues, no environment mismatch.Why ENACT.md?
SKILL.md files describe what an AI tool does, but don't specify how to run it. You still need Python, Node, or the right libraries installed.
ENACT.md adds execution fields so tools bundle their own environment. Every tool runs the same way, everywhere—in an isolated container with full reproducibility.
Containerized Execution
Tools bundle their runtime environment. No more installing Python 3.11 vs 3.12, no conflicting dependencies, no missing libraries.
Environment & Secrets
Define environment variables and mark secrets in your tool definition. Clients handle secure storage and injection at runtime.
Semantic Versioning
Every tool has a version. Pin dependencies, track changes, and ensure reproducible results across teams and environments.
Self-Documenting
The same file that defines execution also contains documentation. Markdown after the frontmatter describes usage, examples, and edge cases.
MCP Compatible
Native support for Model Context Protocol. AI agents can discover, understand, and invoke tools with typed inputs and outputs.
SKILL.md Compatible
Every ENACT.md is a valid SKILL.md. Use the same format for documentation-only tools and executable tools.
ENACT.md vs SKILL.md
ENACT.md is a strict superset—every SKILL.md field works in ENACT.md
One ENACT.md works across many tools
Your tool definitions work with AI coding agents, automation platforms, and more
Registries
Discover and publish ENACT.md tools
Examples
Real-world ENACT.md files from the community
---
name: "enact/pdf-extract"
version: "2.1.0"
description: "Extract text and metadata from PDF files"
from: "python:3.12-slim"
build: "pip install pymupdf"
command: "python extract.py ${file_path}"
timeout: "2m"
inputSchema:
type: object
properties:
file_path:
type: string
description: "Path to the PDF file"
required: ["file_path"]
outputSchema:
type: object
properties:
text:
type: string
page_count:
type: integer
---
# PDF Extractor
Extracts text content and metadata from PDF files using PyMuPDF.---
name: "enact/screenshot"
version: "1.3.0"
description: "Capture screenshots of web pages"
from: "mcr.microsoft.com/playwright:latest"
command: "npx playwright screenshot ${url} screenshot.png"
env:
VIEWPORT_WIDTH:
description: "Browser viewport width"
default: "1280"
inputSchema:
type: object
properties:
url:
type: string
format: uri
description: "URL to capture"
---
# Web Screenshot Tool
Captures full-page screenshots using Playwright.How to use ENACT.md
Create an ENACT.md file
Add an ENACT.md file to your tool directory. Define your container image (from), build steps, and execution command in YAML frontmatter.
Define your schema
Specify inputSchema and outputSchema using JSON Schema. AI agents use this to understand your tool's inputs and outputs.
Add documentation
Write markdown after the frontmatter. Describe usage, examples, and edge cases. The same file documents and executes your tool.
Test locally
Run your tool in a container locally. It runs exactly as it will for everyone else—no surprises in production.
Share your tool
Publish to a registry or share the file directly. Others can run your tool with the same reproducible results.
Iterate with versions
Update your tool by bumping the version. Semantic versioning lets users pin to stable versions they trust.
# Run any ENACT.md tool in a container
$ docker run -v ./ENACT.md:/tool/ENACT.md enact-runner
◐ Parsing ENACT.md...
◇ ✓ Found: enact/firecrawl@1.1.0
◐ Building python:3.12-slim container...
◐ Running: python firecrawl.py scrape https://example.com
◇ ✓ Execution complete
{"title": "Example Domain", "content": "This domain is for use in..."}FAQ
How does ENACT.md relate to SKILL.md?
ENACT.md is a strict superset of SKILL.md. Every SKILL.md field works in ENACT.md. The difference is ENACT.md adds execution fields (from, build, command) so tools can actually run in containers.
Can I use my existing SKILL.md files?
Yes! Any valid SKILL.md works as-is since ENACT.md is a strict superset. You can optionally add execution fields if you want to make them runnable in containers.
Why containerized execution?
Containers solve the 'works on my machine' problem. Your tool runs the same way everywhere—same Python version, same dependencies, same behavior. No more debugging environment mismatches.
How do I handle secrets and API keys?
Define secrets in the env field with secret: true. The ENACT.md format specifies which values are secrets—client implementations handle secure storage and injection.
What container images can I use?
Any Docker-compatible image works—Docker Hub, GitHub Container Registry, or other OCI registries. Use python:3.12-slim, node:20-alpine, or bring your own.
What are the required fields?
For executable tools: name, from, and command are required. For schema validation, inputSchema is recommended. Everything else is optional.
Can tools have timeouts?
Yes! Use the timeout field to specify maximum execution time (e.g., '30s', '5m'). This helps prevent runaway processes and manage resource usage.
Is ENACT.md an open standard?
Yes! ENACT.md is open source under Apache-2.0. The specification is available on GitHub and we welcome contributions.