Agent Resource Manager

A nearly stateless CLI that copies skills, agent configurations, and agent instructions between an agent resource database and folders a local coding agent already loads.

The manager remembers only which database to use. It does not track installs, dest directories, or versions on disk. Every copy names a dest with --dir. The local agent owns that folder after the copy.

| Kind | What it is | Typical dest | | --- | --- | --- | | skill | Task-specific procedural knowledge (SKILL.md) | a skills directory | | agent | Product-native config for a named sub-agent (.toml, .md, …) | an agents directory | | instruction | Standing instructions for the current agent (AGENTS.md) | user- or project-level instruction dir |

This repository is the manager software (@acercyc/agent-resource-manager). Packages live in a separate agent resource database (GitHub repo or local folder). The two are never mixed.

How to use the CLI is this README. Package format, database layout, and copy rules: docs/DESIGN.md. Implementation history: docs/history.md.

Requirements

• Node.js 20+
• git on PATH when the database is a GitHub repository, or when a local database folder is a GitHub checkout that should commit/push on publish

Install

npm install -g @acercyc/agent-resource-manager
agent-resource-manager --help

From this repository:

npm install
npm run build
npx agent-resource-manager --help

During development:

npx tsx src/cli.ts --help

On PowerShell, pass CLI flags after -- if you use npm run dev, or call npx tsx src/cli.ts directly so npm does not swallow --dir.

Quick start

agent-resource-manager init
agent-resource-manager database set github:owner/agent-resources
# or a local folder:
# agent-resource-manager database set ./agent-resources

agent-resource-manager list
agent-resource-manager info skill:literature-review

agent-resource-manager install skill:literature-review --dir ~/.codex/skills
agent-resource-manager install agent:light-worker --dir ~/.codex/agents
agent-resource-manager install instruction:user-canonical --dir ~/.agents

Edit the dest copy, then write it back. publish also creates the database package when dest is a folder with a valid resource.json and that name is not in the database yet:

agent-resource-manager publish skill:literature-review --dir ~/.codex/skills
agent-resource-manager publish skill:topic-literature-review --dir ./package

install / update copy database → dest. publish copies dest → database. unpublish deletes the database package only; dest copies are left alone. remove deletes the dest copy only; it does not change the database. remove still works when the database package is already gone (orphan dest cleanup).

Concepts

Agent resource database. Canonical packages. A GitHub repository or a local folder with the same layout. Set once with database set. Override per command with --database.

Dest folder. Where Codex, Cursor, Claude, or another tool already loads files. Always passed as --dir. The manager never infers product paths.

Refs. Always kind:name (skill:literature-review, agent:light-worker). Bare names are rejected.

Nearly stateless. ~/.agent-resource-manager/config.json stores the database location. GitHub clones may be cached under ~/.agent-resource-manager/cache/ for performance. There is no install ledger. Override the home directory with AGENT_RESOURCE_MANAGER_HOME.

Agent resource database

GitHub vs local folder is transport only. The tree is the same:

<database-root>/
  skills/<name>/resource.json
  agents/<name>/resource.json
  instructions/<name>/resource.json

Every package is a directory with resource.json. Skills usually deploy as a directory. Agent configs and instructions usually deploy as a single file, keeping the entry’s native filename (light-worker.toml, AGENTS.md).

Database references:

| Input | Transport | | --- | --- | | ./path, ~/path, absolute paths | local | | github:owner/repo | GitHub | | owner/repo | GitHub | | https://github.com/owner/repo | GitHub |

Private GitHub databases use your existing git credentials. The CLI clones over HTTPS and does not store tokens. gh auth login (HTTPS) or Git Credential Manager is enough when git clone already works for that repo. A local checkout can be used as the database with no GitHub access.

When the database is github:owner/repo, publish commits and pushes from a cache clone (only the package path is staged). When it is a local folder that is a git checkout whose origin is GitHub, publish writes files in place, then commits and pushes that package path in the working tree (no second cache clone). Other local folders only get a file write; commit and push yourself if needed. If push fails after a successful local commit, the commit is kept and the next cache sync will not wipe it.

Use database sync to explicitly refresh the GitHub cache clone (git fetch + reset to origin/HEAD, unless the cache has unpushed commits). Local folder databases are already live — database sync reports that and does not pull. To copy a newer package into a dest folder, run update <kind:name> --dir <path> after syncing.

Commands

| Command | Role | | --- | --- | | init | Create ~/.agent-resource-manager/config.json | | database get | Show the configured database | | database set <source> | Set the database | | database sync | Refresh the GitHub database cache clone | | list [--kind skill\|agent\|instruction] | List packages | | info <kind:name> | Show package metadata | | install <kind:name> --dir <path> | Copy database → dest | | update <kind:name> --dir <path> | Overwrite dest from the database | | publish [<kind:name>] [--dir <path>] | Copy dest → database (creates the package if it is new) | | unpublish <kind:name> | Delete database package | | remove <kind:name> --dir <path> | Delete dest copy | | doctor | Check config and database reachability |

publish without a ref is allowed when the current working directory is a dest package that contains resource.json. A new database package always needs that dest directory and resource.json; a lone dest file (typical after file-deploy install) cannot create a package.

Bundled operator skill

This npm package ships a bundled operator skill that teaches coding agents how to use this CLI. It is part of the manager software, not a package in the agent resource database. Source: skills/agent-resource-manager/SKILL.md. Reserved ref: skill:agent-resource-manager.

Install (or refresh) into a skills dest from the npm package — never from the database:

agent-resource-manager install skill:agent-resource-manager --dir ~/.codex/skills
# or any other skills dest:
# agent-resource-manager install skill:agent-resource-manager --dir <skills-dest>

Security

Database content is untrusted. Install and publish do not run package scripts. Symlinks inside packages are rejected. Paths are confined to --dir on install and to the package directory on publish.

Development

npm test
npm run build

License

MIT