Agent Manager

A terminal UI tool for installing AI agent skills and provisioning Atlassian Rovo agents from a centrally-hosted bundle.

Agent Manager downloads a versioned bundle of skills and agent configs from a URL you provide, then lets you interactively install skills to your coding tools via symlinks.

Quick Start

npx @ai-agent-manager/cli https://your-bundle-server.com

This fetches the version index from https://your-bundle-server.com/agents/index.json, downloads the latest versioned bundle (e.g. agents/1.2.0/bundle.zip), caches it locally at ~/.agentman/, and opens an interactive menu.

Requirements

• Node.js 22 or higher
• Playwright (optional, only needed for Rovo agent provisioning)

Usage

Run with npx

npx @ai-agent-manager/cli <base-url>

The tool fetches /agents/index.json from the base URL to discover available versions, then downloads the latest versioned zip (e.g. /agents/1.2.0/bundle.zip). You only need to pass the root URL of the bundle server.

Force re-download

Re-download the latest bundle even if a cached version exists:

npx @ai-agent-manager/cli <base-url> --update

Help

npx @ai-agent-manager/cli --help

Interactive Menu

Once launched, the TUI presents the following options:

• Install Skills -- Choose system-wide or repository-scoped installation, select a coding tool, then choose which skills to install or uninstall via symlink.
• Rovo Agents -- Provision Atlassian Rovo agents using Playwright-driven browser automation. Requires Playwright to be installed.
• Manage Versions -- View cached bundle versions, switch the active version, or remove old ones.
• Check for Updates -- Re-download from the server and switch to the new version if one is available.
• Exit -- Quit the tool.

Beta / prerelease builds

Pre-release builds are published to GitHub Packages when a pre-release version tag is pushed (e.g. v1.2.3-beta.0) as @deloitte-uk-innersource/ai-agent-manager with the beta dist-tag. These require authentication to consume.

Authenticate with GitHub Packages

You need a GitHub Personal Access Token (classic) with at least read:packages scope.

1. Create a token at https://github.com/settings/tokens — select Generate new token (classic) and tick read:packages.

2. Add the following to your ~/.npmrc (create the file if it does not exist):

   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

   Replace YOUR_GITHUB_TOKEN with the token you just created.

3. Tell npm to resolve the @deloitte-uk-innersource scope from GitHub Packages. Create or update a .npmrc in the directory you are running npx from (or add it to your home directory alongside the auth token):

   @deloitte-uk-innersource:registry=https://npm.pkg.github.com/

Run the beta build with npx

npx @deloitte-uk-innersource/ai-agent-manager@beta https://your-bundle-server.com

Or pin to a specific version:

npx @deloitte-uk-innersource/[email protected] https://your-bundle-server.com

Supported Coding Tools

Skills are installed as symlinks into each tool's native skills directory:

| Tool | Install Path | |------|-------------| | Claude Code | ~/.claude/skills/<skill-name>/ | | Windsurf | ~/.codeium/windsurf/skills/<skill-name>/ | | GitHub Copilot | ~/.copilot/skills/<skill-name>/ | | Cursor | ~/.agents/skills/<skill-name>/ |

Cursor does not have a global filesystem skills path. Skills are installed to ~/.agents/skills/ using the cross-client convention. You may need to configure Cursor to discover this location.

On Windows, if symlink creation fails (requires admin or developer mode), the tool falls back to copying the skill directory.

Repository-Scoped Installation

Skills can also be installed into a specific git repository instead of system-wide. When you run Agent Manager from inside a git repo, the scope selector offers System-wide or This repository.

Repository-scoped installs use tool-specific paths within the repo:

| Tool | Repo Install Path | | -------------- | --------------------------------------------- | | Claude Code | <repo>/.claude/skills/<skill-name>/ | | Windsurf | <repo>/.windsurf/skills/<skill-name>/ | | GitHub Copilot | <repo>/.github/copilot/skills/<skill-name>/ | | Cursor | <repo>/.cursor/skills/<skill-name>/ |

Symlinks still point to ~/.agentman/bundles/<version>/<skill> -- the bundle content is not copied into the repo.

A .agentman.json file is created at the repo root to track the pinned bundle version and installed skills. Commit this file so your team shares the same version.

Bundle Format

The tool expects the bundle server to host an index at <base-url>/agents/index.json listing available versions, with versioned zip files at <base-url>/agents/<version>/bundle.zip. Each zip contains:

• manifest.json -- Bundle metadata with version (semver) and published (ISO date).
• Skill directories -- Each containing a SKILL.md file per the agentskills.io specification. Optionally includes scripts/, references/, and assets/ subdirectories.
• Rovo agent directories -- Each containing a rovo-agent.yaml file with the agent configuration for Playwright automation.
• README.md frontmatter -- Each directory can have a README.md with YAML frontmatter (name, description, tags[]) used for display metadata in the TUI.

How It Works

1. On first run, the bundle is downloaded and extracted to ~/.agentman/bundles/<version>/.
2. A ~/.agentman/current symlink points to the active bundle version.
3. Multiple bundle versions can coexist. Use "Manage Versions" to switch between them.
4. When you install a skill, the tool symlinks the entire skill directory from the cached bundle into the target tool's skills path.
5. Installation records are tracked in ~/.agentman/config.json (system-wide) or .agentman.json at the repo root (repository-scoped).

Development

Setup

cd agent-manager
npm install

Run locally

npm run dev -- https://your-bundle-server.com

Build

npm run build

Produces compiled output in dist/.

Tests

npm test            # run once
npm run test:watch  # watch mode

Type Check

npm run typecheck

Publishing

Publishing is handled automatically by CI when a version tag is pushed. The version in package.json is set from the tag at publish time — no manual version bumps are needed. The publish CI job runs on Node 24+ as required for npm trusted publishing.

| Tag pattern | Registry | Package name | Dist-tag | |-------------|----------|--------------|----------| | v*.*.* (stable) | npmjs.org | @ai-agent-manager/cli | latest | | v*.*.*-* (pre-release) | GitHub Packages | @deloitte-uk-innersource/ai-agent-manager | beta |

To publish:

# Stable release
git tag v1.3.0
git push origin v1.3.0

# Beta release
git tag v1.3.0-beta.0
git push origin v1.3.0-beta.0

The production build is published to https://www.npmjs.com/package/@ai-agent-manager/cli

Required secrets

The following secrets must be configured in the repository's Settings → Secrets and variables → Actions:

• NPM_TOKEN — an npm automation token with publish access to the @ai-agent-manager organisation. Generate one at https://www.npmjs.com/settings/~/tokens (select Automation type).

The develop → GitHub Packages job uses the built-in GITHUB_TOKEN — no extra secret is needed.

Manual publish (npmjs.org)

If you need to publish manually outside of CI, make sure you are logged in with access to the @ai-agent-manager org:

npm login

Set the version and publish:

npm version 1.3.0 --no-git-tag-version
npm publish

prepublishOnly runs typecheck, tests, and a fresh build automatically before publishing.