Agent Solutions (ags)

A personal, CLI-based catalog of approved reusable solutions, written for coding agents.

You keep a registry of solutions you trust: libraries, Asset Store packages, your own code, and small snippets. You choose which of them each project may use. Your coding agent (Claude Code or Codex) then reads a compact catalog before it builds a subsystem, instead of reinventing one. ags keeps that catalog, delivers agent-ready CNL-P documentation on demand, and records who installs each solution.

How it works

 GitHub: <you>/ags-registry          one Git repository you own
   solutions/<id>.yaml               a card per solution: what it provides, where it comes from,
                                     who installs it, where its documentation lives
   docsets/<id>/<version>/           agent-ready docs of third-party solutions
        │
        │  ags setup   (once per machine)
        ▼
 <ags-home>                          local copy of the cards; also installs the ags-registry
                                     skill, so an agent can maintain the registry for you
        │
        │  ags init   (once per project)
        ▼
 your project/.ags/                  the solutions this project may use, their docs, and
   CATALOG.md                        the catalog the agent reads first

Docsets for your own solutions can live in the solution's own repository at a pinned tag. The registry card then points there, and projects download them from that repository.

Install

npm install -g agent-solutions

Requires Node.js >=22.19 and git on PATH. cnlp-kit is optional: when it is present, ags docs attach validates a docset.

The package has no install script: npm 12 blocks install scripts by default, and older versions hide their output. Setup happens on first use instead, in one of two ways:

• In a terminal: run any ags command. On a fresh machine it asks for the registry URL and the branch, sets itself up, then continues with your command. You can also run ags setup --registry https://github.com/<you>/ags-registry.git directly.
• Through your agent: ask it for anything ags-related. The first ags call reports not set up … an agent asks the operator for the registry URL and runs that command itself. The agent then asks you for the URL and runs ags setup for you.

The registry repository needs at least 1 commit. Create it on GitHub with a README.

Fill the registry by talking to your agent

ags setup installs the operator skill ags-registry for Claude Code (~/.claude/skills/) and Codex (~/.agents/skills/). In any session, say for example:

add DOTween from the Asset Store; its docs are at https://dotween.demigiant.com/documentation.php

The agent derives what it can, asks only for what is missing, shows you the YAML card, and after your confirmation runs ags registry add and ags registry commit itself. The same works for "change…", "remove…", "approve the drafts" and "write a docset for…".

A CNL-P docset you already wrote works the same way: when the agent asks where the documentation is, name its folder. The agent takes the version from its index.md, puts it where the registry expects it, asks who commits and pushes, and runs ags docs attach (details).

Your agent only loads the skill's name and description until the skill is used. If you still do not want it:

ags skills list                    # state per agent
ags skills remove ags-registry     # remembered: a later ags setup will not reinstall it
ags skills install ags-registry    # bring it back

Use it in a project

cd my-unity-project
ags init --solutions dotween,astar-pathfinding-project

ags init writes .ags/ (profile, catalog, docsets), installs the project skill ags, and adds a short block to CLAUDE.md and AGENTS.md. From then on the agent:

• reads .ags/CATALOG.md before it builds a reusable subsystem;
• proposes a solution from the catalog, or asks you before it writes its own;
• installs a solution itself only when its card says installed_by: agent and you agree, and otherwise asks you to install it;
• adds or removes profile entries only with your agreement.

$ ags list
astar-pathfinding-project  unpinned  ok       installed
dotween                    1.2.765   ok       not installed
object-pool                unpinned  none     unknown

$ ags check
check: 0 error(s), 0 warning(s)

Updating

npm update -g agent-solutions   # replaces the program only; your setup and projects stay
ags setup                       # refreshes the ags-registry skill
ags init                        # inside a project: refreshes its skill and block;
                                # the picker opens with the current set checked

A skill file or block you edited by hand is never overwritten. The new version is written beside it as .incoming, and ags prints a CONFLICT line.

Key features

• One catalog per project: .ags/CATALOG.md lists only the selected solutions, within 3,000 tokens.
• Documentation on demand: docsets are fetched with git alone, from the registry or from the solution's own repository at a pinned tag. ags docs <id> prints the path and repairs a missing or stale copy.
• Clear install responsibility: every card says who installs the solution: installed_by is agent or operator, and release binaries use the download type.
• Version-aware: each docset carries a compatible range, so a version bump does not force new documentation.
• Safe re-runs: ags init and ags setup never overwrite your edits.
• Self-diagnosing: ags check validates the profile, the cards, the catalog, the docsets and the install records.
• Agent-ready: read commands support --json, and every failure has a stable exit code and error code.

Command overview

| Area | Commands | |------|----------| | Machine | ags setup, ags home, ags skills list\|install\|remove | | Registry | ags registry list\|add\|approve\|edit\|remove\|sync\|commit | | Project | ags init, ags profile show\|add\|remove\|edit, ags list, ags search, ags show, ags status, ags catalog generate, ags check | | Documentation | ags docs <id>, ags docs fetch\|generate\|attach\|confirm-compatible\|set-range\|status |

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Install, set up the registry, initialise a project | | CLI Reference | Every command, its flags and its exit codes | | Workflows | Registry growth, documentation authoring, the upgrade chain | | Development | Repository layout, tests, build, release | | Product Requirements | The normative PRD this implementation follows |

License

MIT; see LICENSE.