Create an agent package

This guide walks you through creating an agent package from scratch. By the end you will have a working agent that researches a topic on the web and produces a structured report — ready to share or publish.

Prerequisites

• APKG CLI installed — see Installation if you haven’t set it up yet.
• A default tool configured — see Quick Start to set up tool auto-configuration.

Skill vs. agent — which one do I need?

	Skill	Agent
Focus	One capability (review code, generate tests)	A multi-step workflow that orchestrates tools
Tools	Declared in the definition file frontmatter	Declared in apkg.json with package references
System prompt	The definition file body is the prompt	A separate systemPrompt field or file
Model preference	None — uses whatever model the user runs	Can declare preferred models via modelPreference
When to choose	The task is a single, well-scoped action	The task involves planning, multi-tool coordination, or autonomous decision-making

If your package does one thing well, start with a skill. If it orchestrates a workflow across multiple tools, an agent is the right fit.

Initialize the package

Create a directory and scaffold the manifest:

mkdir research-agent && cd research-agent
apkg init

Answer the prompts:

Prompt	Value
Package name	@<your-username>/research-agent
Version	0.1.0
Package type	agent
Description	Researches a topic on the web and produces a structured report
License	MIT
Keywords	research, web-search, report

This creates an apkg.json:

{
  "name": "@alice/research-agent",
  "version": "0.1.0",
  "type": "agent",
  "description": "Researches a topic on the web and produces a structured report",
  "license": "MIT",
  "keywords": ["research", "web-search", "report"]
}

Write the system prompt

The system prompt defines the agent’s personality and high-level behavior. It is referenced from apkg.json and resolved at setup time.

Create a prompts/ directory and add system.md:

mkdir prompts

prompts/system.md

You are a research agent. Your job is to investigate a topic thoroughly
and deliver a well-structured report.

## Workflow

1. **Clarify the question** — If the user's request is ambiguous, ask one
   round of clarifying questions before starting research.

2. **Search** — Use web search to find relevant, authoritative sources.
   Prefer primary sources (official docs, papers, announcements) over
   secondary commentary.

3. **Read and extract** — Open promising results and pull out key facts,
   data points, and quotes. Note the source URL for each.

4. **Synthesize** — Combine findings into a coherent narrative. Resolve
   contradictions between sources by citing both and noting the
   disagreement.

5. **Deliver the report** — Write the report in the following structure:
   - **Summary** — 2-3 sentence overview.
   - **Key findings** — Bulleted list of the most important facts.
   - **Details** — Longer discussion organized by subtopic.
   - **Sources** — Numbered list of URLs cited in the report.

## Guidelines

- Do not fabricate information. If you cannot find a reliable source, say so.
- Keep the report concise — aim for quality over quantity.
- When quoting a source, use blockquotes and cite the URL.

Why a separate file?

Keeping the system prompt in its own file makes it easier to iterate on the prompt without touching the manifest. It also keeps apkg.json readable when prompts are long. You can inline the prompt directly in apkg.json if it is short, but a file is recommended for anything beyond a sentence or two.

Declare tool bindings

Agent packages declare their tool dependencies in the agent.tools array. Each entry references another APKG package by its scoped name.

Update apkg.json to add the agent-specific fields:

{
  "name": "@alice/research-agent",
  "version": "0.1.0",
  "type": "agent",
  "description": "Researches a topic on the web and produces a structured report",
  "license": "MIT",
  "keywords": ["research", "web-search", "report"],
  "agent": {
    "tools": [
      { "name": "web-search", "package": "@acme/web-search", "required": true },
      { "name": "formatter", "package": "@acme/fmt", "required": false }
    ],
    "systemPrompt": "prompts/system.md",
    "modelPreference": ["claude-sonnet-4-6"]
  }
}

Tool object fields

Field	Type	Default	Purpose
name	string	—	A display name for the tool.
package	string	—	The scoped APKG package that provides the tool.
required	boolean	true	Whether the agent can function without this tool. Mark optional tools as false — the agent will still work if they are unavailable.

The packages listed in tools must also appear in your dependencies so they are installed alongside the agent:

apkg add @acme/web-search
apkg add @acme/fmt

This updates apkg.json:

{
  "dependencies": {
    "@acme/web-search": "^1.0.0",
    "@acme/fmt": "^0.5.0"
  }
}

Set model preferences

The modelPreference field is an ordered list of model IDs. The first model in the list is the preferred one; subsequent entries are fallbacks.

{
  "modelPreference": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

This is a hint, not a hard requirement — the user’s environment and billing plan determine which model actually runs. If no preference is set, the assistant uses whatever model the user has configured.

Add a definition file

Just like skill packages, agents can include .md definition files with frontmatter. These are copied into the tool’s configuration directory (.claude/agents/ for Claude Code) and give the assistant additional context about the agent.

Create research-agent.md in the package root:

---
name: research-agent
description: Researches a topic on the web and produces a structured report
tools: WebSearch, WebFetch, Read, Write
---

You are a research agent. When the user asks you to research a topic:

1. Search the web for authoritative sources.
2. Read and extract key information from promising results.
3. Synthesize findings into a structured report with summary, key findings,
   details, and sources.

Always cite your sources. Do not fabricate information.

If no definition files are found, APKG generates a summary from the manifest fields (system prompt, tools, model preferences). Providing your own definition file gives you full control over what the assistant sees.

Test locally

Install the agent from its local path into a test project:

cd ~/my-test-project
apkg add ../research-agent

Open your AI coding tool and try:

Research the latest changes in the Rust 2024 edition and write a report.

Iterate on the system prompt and definition file until the results are consistent. Re-run apkg add ../research-agent after each change.

Publish

Once the agent works well:

cd ~/research-agent
apkg login   # if not already logged in
apkg publish

See Publish your first package for the full publishing walkthrough.

Package structure recap

Here is the final layout of the agent package:

research-agent/
  apkg.json              # Package manifest with agent fields
  README.md              # Human-readable docs for the registry
  research-agent.md      # Definition file (prompt + frontmatter)
  prompts/
    system.md            # System prompt referenced by apkg.json

And the final apkg.json:

{
  "name": "@alice/research-agent",
  "version": "0.1.0",
  "type": "agent",
  "description": "Researches a topic on the web and produces a structured report",
  "license": "MIT",
  "keywords": ["research", "web-search", "report"],
  "readme": "README.md",
  "dependencies": {
    "@acme/web-search": "^1.0.0",
    "@acme/fmt": "^0.5.0"
  },
  "agent": {
    "tools": [
      { "name": "web-search", "package": "@acme/web-search", "required": true },
      { "name": "formatter", "package": "@acme/fmt", "required": false }
    ],
    "systemPrompt": "prompts/system.md",
    "modelPreference": ["claude-sonnet-4-6"]
  }
}

Next steps

• Agent package type — Reference for agent-specific fields and tool setup behavior.
• apkg.json reference — Complete reference for every manifest field.
• Create a skill package — If your package does one thing well, a skill might be a better fit.
• Publish your first package — Publishing workflow, authentication, and verification.