Skip to content

Converting AKD Agents into Plugins

Jump to bottom
NISH1001 edited this page Jul 1, 2026 · 5 revisions

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.

Who this is for

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:

  1. Ask Claude to do the first draft locally — consolidate your existing material into the shape AKD Labs understands, and
  2. Upload that draft into AKD Labs to keep iterating, validate, finalize, and test,
  3. 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.

The whole journey at a glance

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)"]
Loading

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.

Step 1 — Gather what you already have

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.

Step 2 — Ask Claude to produce the first-draft artifact (locally)

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 (one file per topic/domain) + an index
├── tools/           ← the tools the agent uses, described (one folder per tool) + an index
├── output.md        ← how answers should be formatted
├── reasoning.md     ← how the agent should think / its strategy
├── guardrails/      ← safety rules and limits
├── resources/       ← any raw source files you want 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, so it's easy to maintain.
  • List each tool under tools/ with what it does and what it needs.
  • 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.

Step 3 — Bring the draft into AKD Labs

In the AKD Labs dev environment:

  1. Create a new CARE instance for your agent.
  2. Upload the zip into it.

You now land in the workspace with a populated draft instead of an empty interview — a big head start.

Step 4 — Iterate, verify & validate in AKD Labs

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, populated contexts/, documented tools/, 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.

Step 5 — Finalize the artifact

When the workspace is solid, finalize it. This locks in the completed artifact as the agent's source of truth.

Step 6 — Test with a real agent

Before packaging anything, prove it works:

  1. Create an agent that uses the finalized artifact.
  2. Attach the tools it needs (see the tool note below).
  3. 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.

Step 7 — Convert to a skill and open the plugin PR

Once you have a green light:

  1. 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).
  2. Package it as a plugin and open a PR to the akd-plugins repo. The repo's development guide covers the plugin layout, registering it in the marketplace, and testing it locally — follow that for the mechanics.

Handling the agent's tools — the one part that isn't automatic

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.

Quick checklist

  • 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)

Tips & gotchas

  • agents.md is 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.

Related

AKD Plugins Wiki

Clone this wiki locally