agent-roles
Advanced tools
Agent Roles is a host-neutral specification for packaging specialist AI agents as portable, mountable Roles.
A Role bundles everything a specialist agent needs — skills, memory, tool dependencies, plugin content, and host adapter metadata — into a single portable unit. It can be mounted into a target project's agent, then cleanly unmounted when no longer needed, without affecting the main environment, user global config, or other agents.
The specification is designed to push multi-agent collaboration toward clearer structure:
| Audience | Shift |
|---|---|
| Developers | From building isolated skills to shipping complete Roles |
| Users | From managing scattered skills/plugins to managing roles |
Languages: 简体中文 | 日本語 | 繁體中文 | 한국어 | More
A specialist agent's content is typically scattered across multiple directories, config files, and runtimes:
Migrating means manually copying, installing, and debugging. Unmounting means guessing which files belong to the agent versus the main environment or other agents.
Agent Roles organizes all of this into a standardized Role format, so a specialist agent can be defined, distributed, mounted, and unmounted as a single independent unit.
A Role is the core object in Agent Roles — a complete specialist agent definition. It is not just a prompt and not just a skill collection; it is an encapsulation unit that carries its own capabilities, context, and adapter information.
A Role Definition is the manifest file for a Role. It describes the Role's responsibilities, required skills, tool dependencies, plugin content, host adapter configuration, and the rules for mounting and unmounting.
Each Role Definition carries Role revision metadata. version is the Role's
own semantic version, separate from the agent-roles npm/PyPI package version.
Published catalog Roles should also include created_at, updated_at, and a
catalog level so users and hosts can compare Role revisions before installing,
updating, or mounting them.
A Host Adapter describes how a Role enters a specific host environment. The same Role can be read and mounted by multiple hosts. The Host Adapter captures the differences in directory layout, config format, tool entry points, and plugin projection for each host.
| Operation | Description |
|---|---|
| Install | Copy, validate, and record a Role in the local .roles/installed store without changing any project or host runtime |
| Update | Refresh one already installed Role from its original source; it fails if the Role is not installed yet |
| Upgrade | User-facing alias for update; upgrade --all refreshes all installed Roles |
| Mount | Attach a Role to a target project by dynamically loading its contents via an index, establishing connections between the Role, the target project, and the host environment |
| Unmount | Detach a Role from the target project; session files are retained as needed, all other content is cleared immediately, without affecting the main environment, user global config, or other agents |
| Content | Description |
|---|---|
role instructions | Role responsibilities, behavior boundaries, and working style |
skills | Capability modules the role uses |
memory | Memory or project context carried by the role |
tools | Commands, scripts, or external tools the role depends on |
plugins | Plugin content the role projects into the host environment |
host adapters | Adapter metadata for different host environments |
lifecycle rules | Rules for handling mount, update, and unmount |
These are the currently published catalog Roles. Each entry is installable
through agent-roles and may expose host-specific adapters.
0.2.3stableagent-roles add archiagent-roles update archiroles/archi0.2.1experimentalagy) delegation.role_setup runtime setup guidance, a role-scoped MCP/tool manifest, frontend MCP toolbox template content, host adapter notes, and validation prompts.agent-roles add frontendagent-roles update frontendroles/frontend-engineer0.2.2previewagent-roles add motheragent-roles update motherroles/motherThis repository now includes a preview agent-roles package-management CLI. It
is intentionally narrower than the future mount/unmount runtime: it focuses on
role discovery, local installation, updates, sync, diagnostics, and
machine-readable resolution.
Install the current public preview with npm:
npm install -g agent-roles
agent-roles --version
The npm package provides the agent-roles command through a Node wrapper that
invokes the bundled Python module, so it requires Python 3.11+ on PATH.
The PyPI package is prepared but still pending trusted-publishing completion;
once it is live, pipx install agent-roles and pip install agent-roles will
provide the same command and the agent_roles Python module.
The npm package does not bundle the installable roles/ catalog. Role catalog
changes are published through the GitHub catalog, so adding or updating Roles
does not require an agent-roles npm/PyPI package release. Use
agent-roles list to discover available Roles from the configured catalog and
agent-roles add <role> to add only the Roles you need. Role aliases
such as archi resolve to their canonical catalog IDs, such as
agentroles.archi.
Daily commands:
agent-roles list
agent-roles add frontend
agent-roles check frontend
agent-roles update archi
add installs Role source into the local .roles/installed store. check
reports whether a Role is available and installed. update refreshes an
already installed Role and will not silently install a missing Role.
Advanced compatibility commands:
agent-roles install archi
agent-roles install --all
agent-roles upgrade archi
agent-roles upgrade --all
agent-roles sync .
agent-roles doctor archi
agent-roles resolve archi
install and doctor remain stable compatibility names for scripts and Host
Adapters; add and check are the simpler user-facing names. upgrade --all
refreshes every installed Role, and install --all installs every currently
discoverable catalog Role. Add --json when an adapter or automation flow
needs machine-readable output; JSON includes the Role version,
catalog_level, digest, update_reason, and available revision timestamps
when the source Role provides them. Same-version content patches can be
represented by digest changes without publishing a new agent-roles package
version.
Role-private runtime setup should be exposed as one future setup or provider
mount action, not as a nested tools install/doctor/uninstall command tree.
Role-carried setup skills should use broad lifecycle names such as
role_setup when they cover MCP, plugin projection, provider config, repair,
or setup diagnostics. Role config uninstall should be owned by agent-roles
or the Host Adapter layer, not by an in-agent setup script. Tool manifests
remain declarations until a Host Adapter explicitly projects them.
For reusable MCP tools, the preferred model is provider-shared runtime plus
project-private binding. A provider can install the MCP packages and wrapper
commands once, then a lightweight project binding decides which Role tools are
enabled for the current project and supplies project-specific values such as
Figma frames, Storybook URLs, or local app URLs. When the provider supports it,
one agent-roles bridge/router should be projected into provider config so new
projects can reuse downloaded tools without globally exposing every Role tool.
By default, the CLI discovers Roles from the current catalog-like directory and
from the public agent-roles-spec catalog cloned into ~/.roles/catalogs.
Set AGENT_ROLES_STORE to choose a different store root, AGENT_ROLES_SPEC_HOME
or AGENT_ROLES_CATALOG to point at local catalogs, and AGENT_ROLES_NO_REMOTE=1
to disable the default Git catalog.
The repo-local cli/agent-roles wrapper and python -m agent_roles run the
same CLI module. Host adapters should consume the JSON output; live mount and
unmount commands remain deferred until the Host Adapter contracts stabilize.
The specification is in early design stage.
Current focus:
.roles store behaviorUpcoming: schema expansion, examples, role manager integration, and live mount/unmount runtime.
Host Adapter development will begin with these multi-agent projects:
Adapters for Claude Code, Codex, and other major hosts are also planned. We will actively work toward native Role format support across platforms.
FAQs
Host-neutral role package management preview for Agent Roles.
We found that agent-roles demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST disclosed an unreleased AI tool called V-etalon and opened a broad inquiry into NVD modernization after years of automation plans produced no public enrichment system.
Security News
In his AI Council 2026 talk, Feross Aboukhadijeh covers recent package compromises, vulnerability discovery, and a more automated security model.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.