headless-adapters
Scannednpx machina-cli add skill youdotcom-oss/agent-skills/headless-adapters --openclawFiles (1)
SKILL.md
4.0 KB
Headless Adapters
Purpose
Schema-driven adapter for headless CLI agents. No code required - just define a JSON schema describing how to interact with the CLI.
| Use Case | Tool |
|---|---|
| Wrap headless CLI agent | headless command |
| Create new schemas | Schema Creation Guide |
Quick Start
- Check if a schema exists in schemas/
- Run the adapter:
ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
CLI Commands
headless
Schema-driven adapter for ANY headless CLI agent.
bunx @plaited/agent-eval-harness headless --schema <path>
Options:
| Flag | Description | Required |
|---|---|---|
-s, --schema | Path to adapter schema (JSON) | Yes |
Schema Format:
{
"version": 1,
"name": "my-agent",
"command": ["my-agent-cli"],
"sessionMode": "stream",
"prompt": { "flag": "-p" },
"output": { "flag": "--output-format", "value": "stream-json" },
"autoApprove": ["--allow-all"],
"outputEvents": [
{
"match": { "path": "$.type", "value": "message" },
"emitAs": "message",
"extract": { "content": "$.text" }
}
],
"result": {
"matchPath": "$.type",
"matchValue": "result",
"contentPath": "$.content"
}
}
Session Modes:
| Mode | Description | Use When |
|---|---|---|
stream | Keep process alive, multi-turn via stdin | CLI supports session resume |
iterative | New process per turn, accumulate history | CLI is stateless |
Pre-built Schemas
Tested schemas are available in schemas/:
| Schema | Agent | Mode | Auth Env Var | Status |
|---|---|---|---|---|
claude-headless.json | Claude Code | stream | ANTHROPIC_API_KEY | Tested |
gemini-headless.json | Gemini CLI | iterative | GEMINI_API_KEY | Tested |
Usage:
# Claude Code
ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
# Gemini CLI
GEMINI_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/gemini-headless.json
Creating a Schema
- Explore the CLI's
--helpto identify prompt, output, and auto-approve flags - Capture sample JSON output from the CLI
- Map JSONPath patterns to output events
- Create schema file based on an existing template
- Test with
headlesscommand
See Schema Creation Guide for the complete workflow.
Troubleshooting
Common Issues
| Issue | Likely Cause | Solution |
|---|---|---|
| Tool calls not captured | JSONPath not iterating arrays | Use [*] wildcard syntax - see guide |
| "unexpected argument" error | Stdin mode misconfigured | Use stdin: true - see guide |
| 401 Authentication errors | API key not properly configured | Set the correct API key environment variable (see Pre-built Schemas table) |
| Timeout on prompt | JSONPath not matching | Capture raw CLI output, verify paths - see guide |
| Empty responses | Content extraction failing | Check extract paths - see guide |
Complete troubleshooting documentation: Troubleshooting Guide
External Resources
- AgentSkills Spec: agentskills.io
Related
- agent-eval-harness skill - Running evaluations against adapters
Source
git clone https://github.com/youdotcom-oss/agent-skills/blob/main/.agents/skills/headless-adapters/SKILL.mdView on GitHub Overview
Headless Adapters provide a schema-based way to wrap and validate any headless CLI agent without coding. It includes scaffolding tools and schema-driven compliance testing to ensure consistent interactions.
How This Skill Works
Define a JSON schema describing the CLI interactions (prompt, output, session mode). The adapter reads the schema, launches the CLI, maps JSONPath outputs to events, and streams results, enabling multi-turn conversations or per-turn iterations depending on the session mode.
When to Use It
- Wrap a headless CLI agent with no coding by supplying a schema.
- Create and validate new CLI interaction schemas using the schema creation workflow.
- Achieve reproducible, schema-driven outputs for testing and evaluation.
- Choose between stream (multi-turn) or iterative (per-turn) session modes based on CLI behavior.
- Run compliance and integration tests using pre-built schemas for Claude or Gemini via headless.
Quick Start
- Step 1: Check if a schema exists in schemas/
- Step 2: Run the adapter: ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
- Step 3: Confirm CLI interactions are processed according to the schema and iterate as needed
Best Practices
- Start with an existing schema in schemas/ as a template before creating a new one.
- Align sessionMode with the CLI's capabilities (stream for resumeable sessions, iterative for stateless ones).
- Capture samples from the CLI and map them to robust outputEvents using precise JSONPath patterns.
- Iteratively test and refine prompts, outputs, and autoApprove flags to stabilize interactions.
- Consult the Troubleshooting Guide for common issues like JSONPath mismatches and stdin mode problems.
Example Use Cases
- Wrap Claude Code CLI using claude-headless.json in stream mode and run via bunx headless.
- Wrap Gemini CLI using gemini-headless.json in iterative mode for per-turn execution.
- Create a new schema for a bespoke headless tool and validate it with the headless adapter.
- Test schema-driven interactions by capturing sample JSON outputs and mapping to events.
- Use the pre-built schemas to verify compatibility and accelerate onboarding of a new CLI.
Frequently Asked Questions
Add this skill to your agents
