Skip to content

Converting AKD Agents into Plugins

Jump to bottom
NISH1001 edited this page Jul 2, 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.

Read this first: the artifact is the agent's ground truth — not a project archive

This is the single idea that makes or breaks the conversion. The finished artifact is everything the agent knows, and nothing else. The agent reads it as truth — it never sees how it was built.

So the artifact holds only agent-facing knowledge: contexts/, tools/, guardrails/, reasoning.md, output.md, and the agents.md prompt. It must not carry the human process trail:

  • ❌ Stage-by-stage documents — "Stage 1 – Agent Scope", "Stage 2.1 – Tools Requirement", etc. Stages are how the humans worked, not something the agent should ever read.
  • ❌ Per-person / per-SME folders — one folder per contributor (e.g. sme-1/, sme-2/) plus coordination folders like aggregation/ or results/. During co-design each SME has their own tree; that's internal bookkeeping for humans. A public-facing agent has no reason to know there were multiple SMEs at all.
  • ❌ Prior iterations, meeting notes, review comments, scratch drafts.

The test: if a human needs it to coordinate the project → it's process, keep it out. If the agent needs it to answer a question → it's an artifact, consolidate it in.

Why this matters: everything you leave in the artifact ships to the agent (your resources/ becomes the skill's assets/, and the agent can read all of it). Stage- and SME-level detail doesn't just bloat the bundle — it actively confuses the model, which treats that process noise as ground truth right alongside the real content. When you convert pre-Labs material, either delete the process scaffolding or fold its content into contexts/ (and tools/ / guardrails/) — never carry the structure over.

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

Your material is probably organized by stage (Stage 1, Stage 2.1…) and by person (one folder per SME). That's fine as input — but remember none of that scaffolding survives into the artifact. You're harvesting the content, not the structure.

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
│   ├── 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/                ← OPTIONAL, use sparingly: reference files the agent may cite
│                                verbatim — NOT a dumping ground for old drafts/stages/SME folders
└── 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 short contexts/index.md listing 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-level tools/index.md that lists all the tools and when to reach for each. (One folder per tool keeps things tidy when a tool grows extra notes.)
  • Fold the process material into the content — don't carry it over. Take the substance of the stage documents and per-SME folders and distill it into contexts/, tools/, and guardrails/. Then drop the stage/SME files themselves. The agent gets the consolidated truth, not the paper trail.
  • Use resources/ sparingly — it is not a landfill. Only put files there that the agent might genuinely need to open verbatim (e.g. a spec it must quote). Old drafts, stage docs, per-SME folders, and results don't belong here — summarize them into contexts/ or delete them.
  • The folder itself is the artifact — don't wrap it in an extra artifacts/ folder.

Concrete example — turning a process-shaped dump into an artifact. What people tend to upload (process-shaped — confuses the agent):

resources/
├── astrophysics/
│   ├── Stage 1 - Agent Scope.docx
│   └── Stage 2.1 - Agent Tools Requirement.docx
└── earth-science/
    ├── sme-1/   sme-2/   sme-3/   …   aggregation/    ← per-SME + coordination folders
    └── results/

What the agent should actually get (consolidated — one ground truth):

scope.md                    ← distilled from the "Stage 1 – Agent Scope" docs
contexts/earth-science.md   ← the agreed domain knowledge, merged across all SMEs
contexts/astrophysics.md
tools/<tool>/index.md       ← distilled from the "Stage 2.1 – Tools Requirement" docs
guardrails/…
agents.md

The stage labels and per-SME folders are gone; their content now lives in the right artifact files. No resources/ needed at all here.

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.
  • Hunt down any process leftovers. If a "Stage N …" file, an SME-named folder, or a results/ dump slipped through in the upload, remove it now (or fold its content into contexts/). This is your last chance to catch it before it ships to the agent.
  • 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)
  • Stripped out all process scaffolding — no "Stage N" files, no per-SME folders, nothing dumped in resources/
  • 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

  • Everything left in the artifact ships to the agent. resources/ becomes the skill's assets/, and the agent can read all of it. Stage docs, per-SME folders, and old drafts left behind aren't harmless clutter — the model treats them as ground truth and gets confused. Strip them, or fold their content into contexts/.
  • 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