Guide · Agent skill
How to use the Create Agent Adapter agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The create-agent-adapter skill is a written playbook that an AI agent such as Claude loads so it can help you write a Paperclip agent adapter. An adapter is a self-contained package that lets Paperclip's orchestration layer drive a specific AI agent runtime, such as Claude Code, Codex CLI, a custom process or an HTTP endpoint. This guide is for developers extending the Paperclip codebase; after reading it you will know what the skill does, how to install it, how to phrase requests that trigger it and what you must review before merging the output.
Create Agent Adapterpaperclipai/paperclip · MIT Download the skill Quick start
- 1Download the ZIP. Download the create-agent-adapter skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one repository.
- 3Or upload in the Claude apps. In the Claude apps, open Settings, then Capabilities, then Skills, and upload the ZIP.
- 4Describe the adapter task. Ask in plain language to add or modify a Paperclip adapter, naming the agent runtime and the surfaces involved.
- 5Review and test the output. Read the generated TypeScript, run it through your toolchain and tests, and check the environment test results before merging.
What does the create-agent-adapter skill make the agent do?
Once installed, the agent knows the folder layout a Paperclip adapter needs, the TypeScript interfaces each part must implement, the environment-test contract, and the process for adding or modifying an adapter across the server, UI and CLI surfaces.
The skill's source describes each adapter as a package that provides implementations for three consumers: the server, the UI and the CLI. The skill is a set of instructions in a single file, SKILL.md, so the agent works from that playbook rather than from general knowledge of Paperclip.
- Knows the packages/adapters/<name>/ layout with src/index.ts, src/server, src/ui and src/cli
- Knows the interfaces for the server, UI and CLI registries
- Explains the test contract behind the board UI 'Test environment' button
- Walks through creating a new adapter or modifying an existing one
How do you install the create-agent-adapter skill?
Download the skill ZIP from this page and unzip it. The skill lives in a folder that contains SKILL.md. Place that folder in your personal skills directory, ~/.claude/skills/, or in a project's .claude/skills/ directory if you want it limited to one repository.
If you use the Claude apps instead of Claude Code, upload the ZIP through Settings, then Capabilities, then Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you trigger the skill with natural requests?
The skill's description tells the agent when to use it: when adding support for a new CLI agent, API agent, custom process, or adapter package. You do not need a special command. Describe the task in plain language and name the Paperclip context so the agent loads the right playbook.
Requests that work well state the runtime you want to wrap and the surfaces involved. The skill covers modifying existing adapters as well as creating new ones, so you can ask for changes across server, UI and CLI together.
- 'Add a Paperclip adapter for our internal CLI agent that takes a prompt on stdin.'
- 'Write a Paperclip adapter that calls our HTTP agent endpoint and shows the run in the board UI.'
- 'Modify the existing Paperclip adapter so its server, UI and CLI parsing stay consistent.'
What files does an adapter contain?
A Paperclip adapter is a self-contained package. The skill describes separate server, UI and CLI entry points, each registered in its own registry. Shared metadata lives in the root index.ts, which the skill says must stay free of Node APIs and React so all three consumers can import it.
The server side provides execute and parse helpers and implements the environment test. The UI side turns agent stdout into transcript entries for the run viewer and builds the adapter config from the creation form. The CLI side formats colored terminal output for paperclipai run --watch.
- Server registry: server/src/adapters/registry.ts, interface ServerAdapterModule
- UI registry: ui/src/adapters/registry.ts, interface UIAdapterModule
- CLI registry: cli/src/adapters/registry.ts, interface CLIAdapterModule
- Shared types: packages/adapter-utils/src/types.ts
packages/adapters/<name>/src/{index.ts, server/, ui/, cli/}What must the environment test return?
Every server adapter must implement testEnvironment. The skill's guidance is to return structured diagnostics rather than throwing for expected findings. Use error for an unusable setup such as a bad working directory, a missing command or an invalid URL; use warn for non-blocking problems; use info for successful checks.
The skill states that severity matters: warnings are not save blockers. Its example is that an explicitly configured API key is info because the user chose it, while an ambient server key that overrides a subscription login stays a warning.
- error: invalid or unusable runtime setup
- warn: non-blocking but important situations
- info: successful checks and context
What do you need before using the skill, and what are the safety notes?
The skill needs a Paperclip monorepo checkout that uses pnpm workspaces, plus the TypeScript and Node.js toolchain for the generated packages. If your adapter wraps an agent runtime, you also need that runtime's own CLI or API available.
The skill does not run scripts and does not use the network, according to its metadata. Its output is TypeScript package code, though, so a human must read, test and review it before it is merged into the repository.
- Requires: pnpm workspaces monorepo checkout, TypeScript and Node.js, and the target agent's CLI or API if you wrap one
- Runs scripts: no
- Uses network: no
- Generated code must be reviewed and tested before merging
What tips help the most?
Give the agent the real output format of the runtime you are wrapping, such as a sample of its stdout, because the parse helpers depend on it. Ask for the server, UI and CLI pieces together so the three registries stay consistent. Keep the metadata file free of runtime dependencies as the skill instructs.
Write the adapter's agentConfigurationDoc as routing guidance with clear use-when and do-not-use-when lines, since LLM agents read it to decide whether the adapter fits a task.
- Paste a sample of the runtime's real output into the request
- Ask for all three surfaces in one pass
- Keep index.ts free of Node APIs and React
- Describe when the adapter should and should not be used in agentConfigurationDoc
What people use it for
- Adding a Paperclip adapter for an internal CLI agent that your team already runs
- Writing an adapter that calls a custom HTTP agent endpoint and shows its runs in the board UI
- Updating an existing adapter so its server, UI and CLI parsing stay consistent after a runtime change
- Creating the testEnvironment checks that report missing commands or bad working directories
Frequently asked questions
Is the create-agent-adapter skill free to use?
The skill is published under the MIT licence, according to this listing. The source does not describe pricing, so check the licence file in the repository for the full terms.
What do I need to install create-agent-adapter?
You need the SKILL.md folder unzipped into ~/.claude/skills/ or a project's .claude/skills/, or the ZIP uploaded under Settings, Capabilities, Skills in the Claude apps. To use the output, you also need a Paperclip monorepo checkout with pnpm workspaces and a TypeScript and Node.js toolchain.
Can I use this skill if I only want to run Paperclip agents?
No. The skill is a contributor guide for writing or changing adapter code. If you only want to use Paperclip or run an existing agent, you do not need it.
Does the skill run code or access the internet?
According to its metadata, the skill runs no scripts and uses no network. It produces code that you must review and test yourself.
What if the skill does not seem to load?
The source gives no troubleshooting steps. Check that the unzipped folder containing SKILL.md sits directly inside the skills folder you chose, and that you are asking about a Paperclip adapter task so the description matches.
How does this compare with writing an adapter by hand?
The skill gives an agent the required folder layout, interfaces and test contract up front, so it covers the server, UI and CLI parts together. Writing by hand gives you full control, but you must track those interfaces yourself. Either way the code needs review.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you are a developer adding a new agent runtime or maintaining an existing adapter in the Paperclip repository, and you want an agent to follow its server, UI and CLI conventions. Pick something else if you only want to use Paperclip, are not comfortable reviewing TypeScript, or are working on a project outside Paperclip, since its interfaces and registry paths are specific to that repository.
Download the skill