-
Notifications
You must be signed in to change notification settings - Fork 1
Converting AKD Agents into Plugins
A step-by-step guide for turning an agent you've already built outside AKD Labs into an installable Claude plugin in the akd-agents marketplace.
You already have an agent designed somewhere else — a pile of prompts and notes scattered across domains (earth science, planetary, astrophysics…), an older iteration or two, a current "final" prompt, and some idea of the tools it needs. You have not run the CARE interview inside AKD Labs.
This guide is the shortcut. Instead of starting the CARE interview from a blank page, you:
- Ask Claude to do the first draft locally — consolidate your existing material into the shape AKD Labs understands, and
- Upload that draft into AKD Labs to keep iterating, validate, finalize, and test,
- then package it as a plugin.
Starting from nothing? If you don't already have artifacts, skip this and run the normal CARE interview in AKD Labs — it walks you through building the artifact from scratch. This guide is specifically for people who already have something and don't want to redo that work.
The goal is freedom: you don't have to have gone through the official interview to get your agent into the marketplace. Bring what you have, bootstrap it, refine it in Labs, and ship.
flowchart TD
A["Existing artifacts<br/>(outside AKD Labs)"] --> B["Claude, locally:<br/>consolidate into<br/>CARE-compatible format"]
B --> C["Zip the draft"]
C --> D["AKD Labs:<br/>new CARE instance +<br/>upload the zip"]
D --> E["Iterate · verify · validate<br/>in the workspace"]
E --> F["Finalize the artifact"]
F --> G["Test a real agent<br/>(attach artifact + tools)"]
G -->|green light| H["Export as a skill"]
H --> I["Open PR to akd-plugins<br/>(package as a plugin)"]
In one line: do the first draft of the artifact locally with Claude, then upload it to AKD Labs to finish it — and finally ship it as a plugin.
Collect everything about the agent into one folder Claude can read:
- Per-domain artifacts (e.g. earth science, planetary, astrophysics)
- Any previous iterations of the agent
- The current best / "final" prompt
- Notes on the tools and data the agent uses
Don't worry about order or overlap — that's what the next step cleans up.
Point Claude at that folder and ask it to reorganize and consolidate everything into the AKD Labs artifact format. That format is just a folder with a predictable layout:
your-agent/
├── scope.md ← what the agent is for, who uses it, what "success" means
├── contexts/ ← the domain knowledge
│ ├── index.md ← short manifest: what each context file covers
│ ├── earth-science.md
│ ├── planetary.md
│ └── astrophysics.md
├── tools/ ← the tools the agent uses — ONE FOLDER PER TOOL
│ ├── index.md ← short manifest: each tool + when to use it
│ ├── <tool_x>/
│ │ └── index.md ← what tool_x does, its inputs/outputs, how it's called
│ └── <tool_y>/
│ └── index.md
├── output.md ← how answers should be formatted
├── reasoning.md ← how the agent should think / its strategy
├── guardrails/ ← safety rules and limits (index.md + one file per rule)
├── resources/ ← any raw source files kept alongside (read-only reference)
└── agents.md ← the final, assembled system prompt for the agent
A few rules to give Claude:
-
The authoritative/final prompt goes into
agents.md. This is the single most important file — it's what actually runs the agent. -
Split domain knowledge across
contexts/, one file per domain or topic, with a shortcontexts/index.mdlisting them. -
Give each tool its own folder —
tools/<tool_x>/index.md— describing what it does, its inputs/outputs, and how it's called, plus a top-leveltools/index.mdthat lists all the tools and when to reach for each. (One folder per tool keeps things tidy when a tool grows extra notes.) -
The folder itself is the artifact — don't wrap it in an extra
artifacts/folder.
When it looks reasonable, zip the folder. This zip is your first-draft artifact — a starting point, not the finished agent.
In the AKD Labs dev environment:
- Create a new CARE instance for your agent.
- Upload the zip into it.
You now land in the workspace with a populated draft instead of an empty interview — a big head start.
This is where the normal CARE process picks back up — now with your draft as the foundation. In the workspace:
- Read through each artifact, fill gaps, and refine with the assistant.
- Make sure the essentials are there: a real
agents.md, populatedcontexts/, documentedtools/, and clear scope/output/guardrails. - The platform will flag what's missing or incomplete — work those warnings down to zero.
Don't skip this step. The local draft gets you started fast, but the AKD Labs iteration is what makes the agent trustworthy. Treat the upload as the beginning of the Labs work, not the end.
When the workspace is solid, finalize it. This locks in the completed artifact as the agent's source of truth.
Before packaging anything, prove it works:
- Create an agent that uses the finalized artifact.
- Attach the tools it needs (see the tool note below).
- Run representative questions across every domain the agent is meant to cover.
Green light = the agent gives correct, grounded answers and its tools actually work. If not, go back to Step 4 and keep refining.
Once you have a green light:
- Export the finalized artifact as a skill. AKD Labs turns the workspace into a skill bundle (the agent's prompt becomes the skill's instructions, and the rest of the artifact rides along as reference material).
-
Package it as a plugin and open a PR to the
akd-pluginsrepo. The repo's development guide covers the plugin layout, registering it in the marketplace, and testing it locally — follow that for the mechanics.
A plugin runs inside Claude Code, not inside AKD Labs. So how your agent called its tools in Labs decides what you need to ship:
| In AKD Labs the agent used… | In the plugin PR you… |
|---|---|
| MCP servers | Nothing to rebuild — just declare the same server(s) in the plugin's MCP config. MCP is already the plugin-native way to expose tools, so it carries straight over. |
| Local / function tools (Labs-native, not MCP) |
Re-create them as runnable scripts in the skill's scripts/ folder, and have the skill's instructions tell the agent to run them. Claude Code can't reach Labs' internal functions, so anything that lived only inside Labs has to travel with the plugin as a script. |
If your agent already used MCP, this step is basically free. If it used local function tools, budget time to turn each one into a small, self-contained script before the PR is ready.
- Gathered all existing material into one folder
- Claude produced a first-draft artifact in the AKD Labs format (with a real
agents.md) - Created a CARE instance in dev and uploaded the zip
- Iterated in the workspace until no warnings remain
- Finalized the artifact
- Tested a real agent (with tools attached) across all target domains — green light
- Exported the skill
- Decided how tools travel: MCP → MCP config, local functions →
scripts/ - Opened the plugin PR to
akd-plugins(following the development guide)
-
agents.mdis the make-or-break file. If the final prompt isn't in it, the artifact is treated as an unfinished draft and the exported skill is flagged as incomplete. -
Empty
contexts/= a shallow agent. If there's no domain knowledge, the agent has nothing to ground its answers in. - Keep the artifact the single source of truth. The same artifact can power other public surfaces too — don't fork the agent's behavior into the plugin by hand; change it in the artifact and re-export.
- The local draft is a scaffold, not the deliverable. The AKD Labs iteration is where it becomes a real agent.
-
Plugin mechanics:
akd-pluginsdevelopment guide - Worked example: Add the AKD Code Search Agent as a Claude plugin
- Starting from scratch instead? Run the CARE interview in AKD Labs — no local draft needed.