@portal-totalcommerce/agent-installer

CLI that installs AI agent definitions, skills, and generates CLAUDE.md files across a multi-project workspace. No AI required at install time — it places static markdown files and injects project names into templates.

Install

# Local (development / before publishing to npm)
npm link

# Global (after publishing)
npm install -g @portal-totalcommerce/agent-installer

Commands

ai-portal init       # Scan workspace and show detected projects
ai-portal install    # Install agents, skills, and generate CLAUDE.md files
ai-portal update     # Update installed files to latest registry versions
ai-portal add        # Add a single agent or skill

install and update share the same scope flags: --workspace (default) walks every detected sub-project, --project acts on the current directory only, and --front / --back set the type for a project whose folder name follows no prefix convention.

ai-portal init

Scans the current directory and detects projects by folder prefix. Does not write any files.

cd my-workspace/
ai-portal init

ai-portal install

Installs agents and skills to each project's .claude/, and generates the CLAUDE.md files.

| Flag | Meaning | |------|---------| | -w, --workspace | Install across every detected sub-project (default) | | -p, --project | Install only in the current directory | | --front | With --project: treat this project as a frontend (React) | | --back | With --project: treat this project as a backend (Node) | | -f, --force | Overwrite existing files |

Workspace mode (default). Scans sub-folders, matches each against a known prefix, and installs per project. Also writes the workspace CLAUDE.md.

cd my-workspace/
ai-portal install

Project mode. Installs into the current directory only — no scanning, no workspace CLAUDE.md. The type comes from the folder prefix when it matches one:

cd my-workspace/mf-campaign/
ai-portal install --project            # detected as mf

When the folder matches no prefix, say a standalone repo that is not a micro frontend, set the type explicitly:

cd portal-web/
ai-portal install --project --front    # React agents + skills, generic CLAUDE.md
ai-portal install --project --back     # backend agents, no skills

--front / --back also override a detected prefix. They are rejected without --project, since in workspace mode every type comes from its folder prefix.

Skips files that already exist. To overwrite:

ai-portal install --force

After install, fill in [COMPLETE] placeholders in each project's CLAUDE.md.

ai-portal update

Compares installed file versions against the registry. Updates only what changed. Takes the same scope flags as install:

ai-portal update                       # every detected sub-project (default)
ai-portal update --project             # current directory only
ai-portal update --project --back      # force the type

In project mode the type is read from the lock written at install time, so --front / --back need not be repeated on every update. Pass them only to change the type.

ai-portal add

Adds a single agent or skill to the workspace, or to a specific project.

ai-portal add agent frontend-agent
ai-portal add skill zustand-state-management
ai-portal add agent frontend-agent --project mf-campaign   # project-level override

Project Types

Projects are detected by folder prefix:

| Prefix | Type | Description | |--------|------|-------------| | mf- | Micro Frontend | React presentation layer | | ms- | Microservice | Independent backend service | | bff | Backend for Frontend | API orchestrator | | ca- | Container App | Batch processing / Excel exports | | acl- | ACL Transformer | Data contract transformation | | adapter- | Adapter | External system connector |

Two more types exist for projects that follow no prefix convention. They are never auto-detected — only reachable via install --project --front or install --project --back:

| Type | Agents | Skills | |------|--------|--------| | front | same as mf- | same as mf- | | back | same as ms- | none |

What Gets Installed

my-workspace/
├── CLAUDE.md                        ← workspace instructions
├── .claude/
│   ├── agents/                      ← shared agents (flat — all projects)
│   │   ├── frontend-agent.md
│   │   └── ...
│   └── skills/                      ← shared skills (flat — all projects)
│       ├── vercel-react-best-practices/
│       └── ...
├── mf-campaign/
│   └── CLAUDE.md                    ← generated from mf template
└── ms-campaign/
    └── CLAUDE.md                    ← generated from ms template

Adding Agents and Skills

See CONTRIBUTING.md for the 2-step process.

Publishing

See docs/publishing.md.

Rules

• Never run npm run build automatically — prohibited in all agents and templates
• Lint is available as a Claude hook only, not an agent step
• All content (templates, CLI output, CLAUDE.md, agents) must be in English