Skill Plugins — Install Once, Use Everywhere

The Problem

You find a skill pack with 14 skills — TDD, debugging, brainstorming, code review, planning workflows. You try to install it:

text

> /skill install obra/superpowers

Failed to install skill: File not found

It fails because the repo contains multiple skills organized as a plugin package, not a single skill. The only option was installing each skill individually — 14 separate commands, each pointing to the exact subdirectory path.

The AI coding ecosystem has converged on plugins (multi-skill packages) as the distribution unit. Claude Code, Cursor, Codex, and OpenCode all support them. Aii CLI didn't — until now.

One Command

text

> /plugin install obra/superpowers

  Parsing source: obra/superpowers
  Detecting plugin manifest...
  Checking .aii-plugin/plugin.json...
  .aii-plugin/plugin.json: File not found
  Checking .claude-plugin/plugin.json...
  Found .claude-plugin/plugin.json (superpowers v5.0.6)
  Installing to: ~/.aii/plugins/cache/superpowers/5.0.6
  Downloading plugin contents...
  Writing files...
  Successfully installed plugin superpowers v5.0.6 (14 skills)

  ✓ Plugin superpowers v5.0.6 installed (14 skills)

One command. 14 skills. Ready to use immediately.

Cross-Tool Compatible

Aii detects plugin manifests in this order:

.aii-plugin/plugin.json — Aii-native format
.claude-plugin/plugin.json — Claude Code compatibility

This means any plugin built for Claude Code works with Aii out of the box. The superpowers plugin by Jesse Vincent — the most popular Claude Code skill pack — installs without modification.

Plugin authors can support both tools by including both manifest files, or just one. The format is identical:

json

{
  "name": "aii-skills",
  "description": "Official Aii skill pack",
  "version": "0.1.0",
  "author": { "name": "AiiWare" },
  "license": "MIT"
}

Namespaced Skills

When you install a plugin, its skills are namespaced to prevent collisions:

text

> /skill list

  PLUGIN: superpowers
    /superpowers:brainstorming
    /superpowers:test-driven-development
    /superpowers:systematic-debugging
    /superpowers:writing-plans
    ...

Type /superpowers:brainstorming to invoke explicitly. Or just /brainstorming — if unambiguous, the shorthand works. If two plugins both provide a skill with the same name, Aii asks you to disambiguate.

Smart Auto-Detection

Don't know if something is a plugin or a single skill? Don't care. /skill install figures it out:

text

> /skill install obra/superpowers
  Detected plugin manifest, installing as plugin...
  Plugin superpowers v5.0.6 installed (14 skills)

> /skill install aiiware/aii-skills/skills/code-review
  Installed skill: code-review

Two-part source (owner/repo) — checks for plugin manifest first. Three-part source (owner/repo/skill) — installs the individual skill directly.

Works With Personas

Plugin skills integrate with the persona system. Add them to your active persona:

text

> /persona add skill superpowers:writing-plans

  + Added skill "superpowers:writing-plans" to aiiware/doer

Check your setup with the enriched status view:

text

> /persona status

  Active: Aii Doer v0.1.0
  Direct and efficient AI assistant that leads with the answer

  Soul: doer
  Theme: classic
  Skills: 5 total
    tdd — Use for any software development...            [persona-bundled]
    debug — Use when encountering bugs...                [persona-bundled]
    superpowers:writing-plans — Use when you have a spec... [customized, plugin: superpowers v5.0.6]
    superpowers:brainstorming — You MUST use this before... [customized, plugin: superpowers v5.0.6]

Every skill shows its source — built-in, persona-bundled, or which plugin (with version). No guessing where a skill came from.

Auto-Triggered

Plugin skills auto-trigger from natural language, just like built-in skills:

text

> review my changes before submitting

  Skill /requesting-code-review activated

Type what you want. The skill intent classifier detects which skill to activate based on your persona context and the available skills — whether they come from a plugin, a persona, or your local .aii/skills/ directory.

Full Lifecycle

bash

# Install
aii plugin install obra/superpowers
aii plugin install aiiware/[email protected]

# List installed plugins
aii plugin list

# Update to latest
aii plugin update superpowers

# Remove
aii plugin uninstall superpowers

All commands work both as CLI (aii plugin ...) and interactive slash commands (/plugin ...).

Storage

Plugins are stored in ~/.aii/plugins/cache/ with version-indexed directories:

text

~/.aii/plugins/
  plugins.json                           # Registry
  cache/
    superpowers/5.0.6/                   # Full plugin snapshot
      skills/brainstorming/SKILL.md
      skills/test-driven-development/SKILL.md
      ...

A plugins.json registry tracks versions, sources, and install timestamps. Update replaces the version directory atomically. Uninstall removes everything cleanly.

Build Your Own

Creating an Aii-compatible plugin is straightforward:

text

my-plugin/
  .aii-plugin/plugin.json     # Plugin manifest
  skills/
    my-skill-a/SKILL.md       # Skill definitions
    my-skill-b/SKILL.md

Each SKILL.md uses standard frontmatter:

markdown

---
name: my-skill-a
description: What this skill does and when to use it
---

Instructions for the AI agent when this skill is activated...

Push to GitHub. Users install with /plugin install your-org/my-plugin. Skills can include supporting files — scripts, reference docs, examples, templates — in subdirectories alongside SKILL.md.

Plugin support ships in Aii CLI v0.14.10. Update with npm install -g @aiiware/aii.