Authoring capabilities

Create#

arcotheon init my-capability --id acme/my-capability --template tool

Templates: skill (a skill only) and tool (a skill plus a Node tool). You get a capability.json, a SKILL.md, a changelog and a README.

The manifest in five minutes#

{
  "adcap": "1.0",
  "id": "acme/my-capability",
  "version": "0.1.0",
  "name": "My Capability",
  "summary": "One line that says what an agent gains.",
  "license": "Apache-2.0",
  "publisher": { "id": "acme" },
  "skills": [{ "path": "skills/my-capability" }],
  "permissions": [
    { "id": "fs:read", "scope": "workspace", "reason": "Read the files you ask it to check." }
  ],
  "tools": [{
    "name": "check",
    "description": "What the tool does, in a sentence an agent can act on.",
    "runtime": { "type": "node", "entry": "tools/check.mjs" },
    "inputSchema": { "type": "object", "required": ["path"], "properties": { "path": { "type": "string" } } },
    "permissions": [{ "id": "fs:read", "scope": "workspace" }]
  }]
}

The full reference is the specification; the JSON Schema is at https://agdc.dev/arcotheon/schema/capability-1.json, so editors can validate as you type.

Writing a tool#

A tool reads one JSON line from stdin and writes one to stdout. In Node:

import { createInterface } from "node:readline";
for await (const line of createInterface({ input: process.stdin })) {
  const call = JSON.parse(line);                // { type:"call", tool, input, context }
  const { workspace, dir, resources } = call.context;
  process.stdout.write(JSON.stringify({ type: "result", output: { ok: true } }) + "\n");
  break;
}

• context.dir is the capability's own directory (read-only); context.workspace is the user's project folder, and is null unless the tool holds a workspace permission.
• Declare resources on the tool and read them from context.resources[id]. Do not download datasets yourself: the host fetches, verifies and caches them, and your tool can then run without network access.
• Reply with {"type":"error","message":"…"} to report failure. Keep paths inside the workspace; the sandbox enforces it, but your tool should check too.
• Python tools work the same way over sys.stdin/sys.stdout; the SDK starts them with python3 -I.
• Native tools: set runtime.type to binary and list one entry per platform. Declare compat.platforms so installs fail cleanly elsewhere.

Validate, build, inspect#

arcotheon validate my-capability        # schema, semantics, referenced files, skill front matter
arcotheon build my-capability --out dist --key acme-publisher
arcotheon verify dist/acme-my-capability-0.1.0.adcap
arcotheon inspect dist/acme-my-capability-0.1.0.adcap

inspect prints what the package contains and the permissions it asks for, exactly what a user will see.

Builds are reproducible. If two builds of the same source differ, that is a bug.

Keys#

arcotheon keys generate acme-publisher      # ~/.config/arcotheon/keys/acme-publisher.json (mode 0600)
arcotheon keys show acme-publisher          # the public half, for the registry

Keep the private key out of Git and CI logs. Registries list only public keys.

Skills compatibility#

Anything under skills/<name>/ that has a valid SKILL.md is a standard Agent Skill. You can copy that directory into any agent's skills folder without Arcotheon.

Ignoring files#

Put globs in .adcapignore (*, **, one per line). .git, node_modules, __pycache__ and *.adcap are always excluded. Symbolic links are an error.