Your next agent should be a directory of skills, not an application

Open a repository for a new “revenue agent” and you will often find the beginnings of another software product: src/, a database layer, provider adapters, a scheduler, an API, an admin interface, and a growing list of dependencies.

Most of that work has little to do with revenue. It rebuilds the loop that calls the model, tracks sessions, exposes tools, selects providers, stores state, and recovers from failure. The useful part is much smaller: how to research an account, qualify it, draft relevant outreach, update the CRM, and decide what happens next.

That distinction leads to a simpler architecture: for most specialized agents, the artifact you build should be a directory, not an application. The runtime software is the harness you already use. Your directory contains only what makes this agent different: concise workspace instructions and composable skills.

AGENTS.md
skills/
  account-research/
  lead-qualification/
  personalized-outreach/
  crm-update/
  follow-up-and-handoff/

AGENTS.md sets local behavior and routes work. Each skill directory owns one repeatable capability.

What an agent actually contains

The word agent currently describes several layers at once. “An agent is a directory” names the specialized artifact your team owns, not the entire running system. Separating the layers makes it easier to see where new code belongs:

1. Model: the reasoning and generation capability.
2. Harness: the execution loop, tools, sessions, context management, provider access, approvals, and recovery behavior.
3. Workspace instructions: the role, boundaries, priorities, and routing rules, often expressed in AGENTS.md or a system prompt.
4. Skills: repeatable procedures, references, and executable tools for specific jobs.
5. Distribution and state: the way the configuration is shared, installed, updated, scheduled, and operated.

A revenue system is mostly layers three and four. Its instructions explain how the agent should behave and when to use each capability. Its skills contain the domain knowledge and repeatable operations. It rarely needs to own the model loop, session store, tool protocol, or provider router.

This is why an AGENTS.md file should be a routing layer, not an encyclopedia. It can tell the agent to qualify an account before drafting outreach, require evidence for claims, and point to the relevant skills. Detailed research criteria, CRM field mappings, templates, and validation logic belong next to the capability that uses them.

OpenAI’s account of harness engineering reaches a related conclusion from software development: agents perform better when the repository makes context, architecture, and validation legible. The answer is not to put every fact in one enormous prompt. It is to design an environment in which the agent can retrieve the right instructions and verify its work.

Skills are the reusable unit

The Agent Skills specification gives that environment a deliberately small shape. A skill is a directory with a required SKILL.md file and optional resources:

SKILL.md
scripts/
  research-company.ts
references/
  qualification-criteria.md
assets/
  account-brief.md

SKILL.md describes when the capability applies and how to use it. references/ holds material that should only enter context when needed. scripts/ contains deterministic operations the agent can run instead of regenerating the same code on every attempt. assets/ provides templates or other output resources.

This layout supports progressive disclosure. The harness can discover a skill from its name and description, load the full instructions when the task matches, and inspect a reference only when a step needs it. The agent receives less irrelevant context, while each capability remains understandable in a normal code review.

Compose a system instead of naming a monolith

Calling something a “revenue agent” suggests one large, indivisible application. The revenue-agent/ directory above shows the actual architecture: a composition of focused capabilities on a shared harness.

Each skill can evolve independently. Account research may use a browser and public sources. Qualification applies your business rules. Outreach turns verified evidence into a message. CRM update performs a narrow, auditable write. Follow-up decides whether to schedule another touch or hand the conversation to a person.

This decomposition also makes skills from different authors useful together. A research skill might return an account ID, verified claims, and source URLs as JSON. Qualification can consume that record and add a score with reasons. Only a passing record moves to outreach, while the CRM skill accepts approved fields and an idempotency key before it performs a write.

Those handoffs make prerequisites, outputs, side effects, and verification visible. Without them, a collection of skills becomes another pile of prompts. With them, a team can replace one research method or CRM integration without rewriting the system.

The repository for a harness such as AgentOS can reasonably resemble a conventional software project because it is runtime software. Copying that structure into every agent profile is a category error. The profile should stay centered on the instructions and capabilities that make it distinct.

Agent Plugins make the composition portable

Skills standardize an individual capability. The new Agent Plugins v1.0.0 specification is a working draft for portable bundles of capabilities. It requires a root plugin.json and discovers supported components from an optional fixed skills/ directory and optional mcp.json file:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "revenue-system"
}

The deliberately narrow specification defines two portable component types: Agent Skills and MCP servers. It does not try to standardize identity, permissions, system prompts, hooks, commands, user interfaces, or installation policy. Those decisions stay with the client.

That boundary matters. You are not asking a user to replace the agent they already trust or install a second software platform. You are packaging self-contained capabilities that can extend it. The current compatible-client registry includes VS Code, Cursor, GitHub Copilot, ChatGPT and Codex, Kiro, Hermes, and OpenClaw, although support varies by component and transport.

An Agent Plugin is therefore a useful distribution unit for a group of skills. Its source bundle is inspectable and version-control friendly. AGENTS.md can remain workspace-specific, while the portable capabilities travel together. Where an entire configured agent must move with its harness-specific behavior, a profile is the broader package.

Reuse the harness that fits the job

Choose a thin harness when you want to shape the runtime in code. Choose a richer profile system when persistent coordination, scheduling, and provider resilience are common requirements rather than your differentiator.

Pi packages serve the first case. They can bundle TypeScript extensions, skills, prompt templates, and themes through npm or Git, while Pi supplies the coding loop, providers, sessions, context handling, and core tools.

Hermes profiles serve the second. A profile distribution can include SOUL.md, configuration, skills, MCP servers, and scheduled work while keeping secrets, memory, and sessions local. The runtime also supplies provider routing, credential pools, fallback providers, and a shared Kanban board for durable work across profiles.

For a persistent outreach or revenue workflow, that substrate is usually more valuable than owning another custom loop. Configure the profile, add the domain skills, and spend engineering time on the parts users can actually distinguish.

Make repeated work executable

A skill can begin as careful written instructions. Once the same transformation or integration appears repeatedly, move that step into a small CLI with explicit inputs, structured output, useful errors, and a verification mode. The Agent Skills guide recommends using scripts for deterministic or repeatedly rewritten work. The agent should decide what to do; the tool should make the operation reproducible.

At Akua, our default for these tools is TypeScript on Bun with Effect 4. We find TypeScript gives generated code a stronger feedback loop across schemas, command arguments, API clients, and structured errors than an untyped script assembled during a run. Effect provides the validation, error handling, retries, and CLI primitives we commonly need.

That is a preference, not a universal benchmark. Python remains an excellent choice for data tooling, scientific libraries, and short operations that the team can inspect easily. Effect 4 is also still a beta; its migration guidance explicitly warns that APIs may change between beta releases. Choose the language your team can review and operate, then keep the command boundary stable for the agent.

Build a new runtime only when the runtime is the product

There are valid reasons to build from scratch: a novel interaction model, a new security boundary, specialized latency constraints, an unusual execution environment, or runtime behavior that existing harnesses cannot express. In those cases, the loop and infrastructure are part of the differentiation.

For most revenue, outreach, research, support, and internal operations agents, they are not. Let the agent you build remain a directory. Start with the harness you already use. Put behavior in concise workspace instructions. Build repeatable work as Agent Skills. Bundle related capabilities as an Agent Plugin. Use a harness-specific profile when you need to distribute the complete operating configuration.

That directory is not a prototype waiting to become an application. It is often the finished architecture.

Deploy the Hermes agent you already built.

Run it as a long-running, stateful workload with per-tenant isolation and an auditable action path.

Deploy your Hermes agent