Holon

Open-source AI assistants on your own computer or server. Assign tasks, track progress, and let them follow up on ongoing work.
Skip to content
Browse docs
On this page

Organize agent skills across dedicated roles

This guide shows how to divide an expanding set of skills across focused, long-lived agents. You will learn how to inspect and enable dedicated skills in conversation via the Web GUI, establish clear authority boundaries, and coordinate specialized agents through work items and delegation—eliminating prompt bloat, tool confusion, and instruction collisions.

Before you start

  • Holon is running with access to the Web GUI (default http://localhost:8080) and at least one configured model.
  • The shared skill library contains relevant skills (official templates bundle standard skills like code-review, ghx, github-review, and sview).
  • No need to memorize complex CLI flags: skill inspection, scoping, and boundary checks can be handled directly in conversation with the agent.

Steps

1. Identify distinct roles and avoid the "God Agent"

Before spinning up an agent, break down recurring workflows into 2 or 3 specialized roles. In a typical engineering team, these roles have very different goals:

Role NameMandateRecommended SkillsAuthority Boundary
Developer (developer)Implement features, fix bugs, run buildsghx, sview, file edit and test toolsWrite access to active worktree; cannot merge unreviewed PRs
Reviewer (reviewer)Scrutinize changes, detect risks, review PRscode-review, github-review, ghxStrictly read-only; never mutates application code
Docs Steward (docs-steward)Maintain documentation, check links, reduce ambiguityinterlinked-markdown-wiki, doc check toolsConfined to docs and assets; no backend write permissions

In the Holon Web GUI, open Templates from the left navigation and create agents from official templates (such as software-developer, code-reviewer, or docs-steward).

2. Instruct the agent to inspect and trim its active skills

Open the chat view for a specific agent (such as the newly created reviewer). Instruct it in plain language to audit its own skill profile:

Check which skills are currently enabled for you. As a code reviewer, confirm whether you have the tools needed for read-only review, and list any unnecessary write or external posting skills that should be disabled.

The agent reads its configuration and active tools, returning a breakdown:

  • Core review tools present: code-review (structured analysis), ghx (PR inspection).
  • Suggested removals: If unnecessary file mutation or external posting tools are attached, the agent flags them for removal.

To enable a specific skill from the shared library, simply ask in conversation:

Enable the github-review skill for yourself to support line-by-line PR reviews, but do not enable any tool that mutates files.

The agent enables the requested skill and confirms its updated tool inventory.

3. Record boundaries permanently in AGENTS.md

To ensure operational discipline survives across future turns, instruct the agent to persist its standing rules in its guidance file:

Please record these operational boundaries in your AGENTS.md:
1. Your sole responsibility is code quality review with primary evidence; never call file-mutation tools on reviewed code.
2. Keep each review scoped strictly to the changes in the current PR.
3. Mark severe defects as blocking and wait for the human author to fix them; do not attempt unprompted fixes.

The agent updates its agent_home/AGENTS.md. These boundaries remain active in every subsequent session.

4. Provide isolated workspace roots

Pair skill boundaries with physical environment isolation:

  1. Dedicated branch worktrees for developers: Instruct the developer agent:

    Attach the current repository and start work on issue-102 inside an isolated Git worktree.

    The agent creates and activates an isolated worktree branch, ensuring edits and test artifacts do not pollute other branches.

  2. Clean read-only projections for reviewers: A reviewer agent inspects canonical checkouts or remote PR commits without holding write locks on active development trees.

5. Coordinate across agents using work items and delegation

When a developer finishes an implementation, do not force the developer agent to review its own work. Instead, delegate:

In the developer agent's chat, instruct:

Implementation and local tests are complete. Create a work item delegating this Git commit to the reviewer agent for review, and wait for its findings.
  1. The developer agent creates a clear WorkItem and issues an asynchronous delegation.
  2. The reviewer agent activates in its clean, read-only context, evaluates the patch using code-review, and logs structured review evidence.
  3. Once review finishes, an event wakes the developer agent to address findings or conclude the task.

Verification and self-checks

Confirm your role and skill isolation with these verification steps:

1. Check prompt overhead

Send a brief message (such as "State your core duties") to the agent in the Web GUI. Verify response latency and token count: a focused role should maintain 3 to 6 active tools, avoiding massive initialization prompts.

2. Test boundary enforcement

Send an intentional out-of-scope command to the reviewer agent:

Change line 20 of src/main.rs to print "hello" and commit the change.

Expected outcome: The reviewer agent explicitly refuses, citing its AGENTS.md contract and read-only review mandate, and suggests handing the task to the developer agent.

3. Verify via CLI (optional)

If you prefer the terminal, verify library registration and per-agent enablement:

# Inspect all skills in the shared library
holon skills catalog

# Inspect effective skills for a specific agent
holon skills list --agent reviewer

Verify that only role-appropriate skills appear in the output.

Frequently asked questions

Q: What if a task requires both coding and documentation updates?

A: Keep the primary feature work item with the developer agent. When code changes land, delegate doc updates to docs-steward under the same workflow. Specialization avoids creating a fragile "all-in-one" persona.

Q: Why not enable all skills globally?

A: Global injection forces every agent to load every tool schema into its prompt. This causes attention dilution, parameter hallucinations between similar tools, and unnecessary token costs on every turn.

Q: Can I apply this role isolation pattern in other tools like Claude Code or Codex?

A: Absolutely. With CLI agents, you can establish dedicated role directories (such as ~/.agents/code-reviewer), place scoped CLAUDE.md / AGENTS.md and local .mcp.json configs inside them, and point the agent to target projects at runtime. For a step-by-step breakdown and architectural evolution, see the blog post Why your agent gets dumber with more skills.

Next steps