Agentville

Agentville is a plugin of skills and agents for running work through agents: a workflow that triages each request and runs the stages it needs, a procedure that delegates one task at a time, writing standards for what agents and people read, standing rules for a delegating agent, and five swappable slots that each agent resolves for itself. It installs as one versioned unit; skills are namespaced agentville:<skill> and agents agentville:<agent>.

Requirements

Agentville runs out of the box on Linux, macOS and Windows, on a laptop or a bare VPS, with Claude Code as the main platform.

• Claude Code, with the plugin installed as described below.
• Git, for the workspace's git-ignore check.
• Python 3.8 or newer, only for the helper scripts of agent-smith, skill-smith and the maintainer skills. They use the standard library alone. Run them as python3 on Linux and macOS and as py -3 (or python) on Windows.
• A shell: bash on Linux and macOS, PowerShell on Windows. Skills and agents write commands in that form and give a PowerShell form where the two differ. A project's CLAUDE.md or steering can name another shell, and that wins.

Nothing else is required. rg, jq and gh are optional: where an agent could use one, it uses Claude Code's own Grep and Read tools or a shell built-in when the tool is missing.

Install

In Claude Code, add the marketplace once, then install one channel:

/plugin marketplace add minhphamdonhat/agentville
/plugin install agentville@minhphamdo

Install one channel at a time: all three load the same names under agentville:, so two would clash. To switch, uninstall the one you have and install the other, for example /plugin uninstall agentville@minhphamdo then /plugin install agentville-beta@minhphamdo.

In Chat, open Customize, then Plugins, choose Add marketplace, enter minhphamdonhat/agentville and install one channel.

From a terminal, the agentville command does the Claude Code install for you: it adds the marketplace, installs one channel and adds the two steering lines shown under Three ways to run it to CLAUDE.md. It needs uv 0.13 or later and Python 3.15; uv downloads that Python when you do not have it. There are two ways to run it, and both take the same options.

Install with uvx

uvx runs the latest published agentville without keeping it installed, and downloads Python 3.15 when it is missing:

uvx agentville install
uvx agentville install --scope project
uvx agentville install --channel beta

If your uv is older than 0.13, upgrade it to 0.13 or later (uv self update). Failing that, add --python 3.15 after uvx to pick the Python by hand.

Install the agentville command

The install script puts a persistent agentville command on your PATH with uv tool install, for your user only. When uv is missing, it downloads Astral's official uv installer, pinned to one uv version, to a temporary file and runs it; it asks first only when you run it at a terminal. It never uses sudo or administrator rights, and running it again upgrades the command.

On Linux and macOS:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.sh | bash

On Windows, in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.ps1 | iex"

On Windows, in the Command Prompt:

curl --proto "=https" --tlsv1.2 -fsSL https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.cmd -o install.cmd && install.cmd && del install.cmd

Then open a new terminal, so that PATH includes the new command, and run agentville install with the options below.

Each script takes an optional version, latest by default, and a switch to install from the GitHub repository instead of PyPI:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.sh | bash -s 0.1.0
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.sh | bash -s -- --from-source

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.ps1))) 0.1.0
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/minhphamdonhat/agentville/main/install.ps1))) -FromSource

Set AGENTVILLE_NO_MODIFY_PATH=1 to leave PATH alone, and AGENTVILLE_YES=1 (or pass --yes, in PowerShell -Yes) to skip the question at a terminal; nothing is asked when CI is set. Upgrade with uv tool upgrade agentville and remove the command with uv tool uninstall agentville.

Installer options

With the claude command on your PATH, the installer runs claude plugin marketplace add and claude plugin install. Without it, the installer writes the same marketplace and plugin entries into Claude Code's settings.json and keeps every other key; it refuses to touch a file that is not valid JSON. User scope writes ~/.claude/settings.json and ~/.claude/CLAUDE.md; project scope writes .claude/settings.json and CLAUDE.md in the project folder. A second run changes nothing. The exit code is 0 on success, 1 when a step fails and 2 for a usage error.

Three ways to run it

In Claude Code, installing Agentville makes pod-lead the main agent by default, so orchestrate runs on every request. Chat and Cowork ignore plugin settings, so there you opt in. Pick one way:

1. Chat. Install the plugin through Customize, then put these lines at the top of your custom instructions:

   - Load `Skill(agentville:root-agent)` and follow it in every reply.
   - Route every request, questions included, through `Skill(agentville:orchestrate)` and follow it.
   

2. Claude Code with pod-lead as the main agent. The plugin ships a settings.json with {"agent": "pod-lead"}, so an installed plugin makes pod-lead the main agent of every session. pod-lead runs every request through orchestrate and follows root-agent. To run it for one session only, start claude --agent agentville:pod-lead. Your own agent setting overrides the plugin's.

3. Claude Code with another agent. The documented ways to use an agent other than pod-lead:

   • Start one session with claude --agent <name>.
   • Name another agent in your own agent key in ~/.claude/settings.json; it overrides the plugin's.
   • Disable the plugin with claude plugin disable agentville@minhphamdo (claude plugin disable --help: "Disable an enabled plugin"). Inferred, not documented: this drops its defaults along with its skills. No documented value unsets agent back to the built-in agent.

   To make that agent follow Agentville, add these lines to your project's CLAUDE.md:

   - Load `Skill(agentville:root-agent)` and follow it in every reply.
   - Route every request, questions included, through `Skill(agentville:orchestrate)` and follow it.
   

   To use your own workflow, fork orchestrate into a new skill and name it in the second line.

What loads where

Chat now shares Cowork's Agent tool and file writing in some accounts, so dispatch can still spawn there; when an agentville: agent type is missing, it falls back to general-purpose. dispatch spawns a variant such as agentville:worker-sonnet-high only when the session's Agent tool has no effort parameter; otherwise it spawns the base agent and passes model and effort, and a missing variant falls back to the base agent with the model passed and records effort unenforced, variant missing.

Updates

In Claude Code, auto-update is off by default for third-party marketplaces. Run claude plugin marketplace update minhphamdo to refresh the listings, which leaves installed plugins as they are. Then run claude plugin update agentville@minhphamdo (or the channel you installed, such as agentville-beta@minhphamdo), or choose Update now in the Installed tab. A running session keeps the old version until you restart it or run /reload-plugins. In Chat, turn on Sync automatically for a github.com marketplace, or use Check for updates.

Skills

Each skill is invoked as /agentville:<name>.

Agents

Each agent reads its role from a <role>ROLE</role> tag on the first line of the brief. dispatch picks the agent for each role.

Each base agent except pod-lead also ships in nine variants, one per model and effort pair, named <base>-<model>-<effort>, with model haiku, sonnet or opus and effort low, medium or high, such as agentville:reviewer-opus-high. That makes 36 variants across worker, validator, reviewer and scout. Each is a copy of its base agent with model and effort fixed in its frontmatter, generated by the maintainer script scripts/gen_agent_variants.py; do not edit a variant by hand. dispatch uses a variant only when the session's Agent tool has no effort parameter.

Context injection

The jobs agents share, a place to write files, a set of check tools and the way a topic's draft, plan and report are recorded, are slots rather than fixed rules. The plugin ships a default skill for each slot, and you swap in your own by binding the slot in your steering. context-injection sets the binding syntax and the order in which bindings are found.

For example, to have every Agentville agent use your own QA tools, put this in your project's CLAUDE.md:

## Context injection

toolbelt: Skill(acme:qa-tools)

In Chat, bindings in custom instructions do not count, and every slot uses the plugin default.

Where agents write

Agents write only under .agentville/topics/ in the project root:

.agentville/topics/
  .gitignore                 # */evidence/, */*/artefacts/, */*/scratch/
  <topic-id>/                # topic documents: tracked
    evidence/run-<N>/        # validator evidence with SHA256SUMS: ignored
    <agent>/artefacts/       # what an agent keeps: ignored
    <agent>/scratch/         # throwaway files, deleted before the report: ignored

The workspace writes its .gitignore on first use when it is missing, and writes nowhere else in .agentville/.

External dependencies

skill-smith calls /skill-creator for evals and description tuning, so install that skill alongside it if you want skill-smith to test what it drafts. Its helper scripts need Python 3 (see Requirements).

Both smiths install only to project scope (.claude/ in the project) or user scope (.claude/ in the home folder). They refuse any plugin folder, Agentville included, and the helper scripts enforce that.

Licence

MIT, see LICENSE.