aria-skills-marketplace

An interactive skills marketplace plugin for opencode CLI. Browse, install, and auto-update skills directly from a GitLab registry — all from inside the opencode TUI.

Features

• /aria-skills-marketplace command — interactive TUI popup to browse and install skills
• Auto-update on startup — fetches registry and silently installs updates for all installed skills
• GitLab-backed registry — skills live in a GitLab repo you control
• Multi-file skills — each skill is a folder (SKILL.md + scripts, assets, references)
• Versioned skills — semver versioning, automatic updates on opencode start
• Zero config JSON — configured via two environment variables only

Installation

1. Install the package

npm install @aria-plugins/aria-skills-marketplace

2. Add the dependency to opencode's package file

Add the package to ~/.config/opencode/package.json.
If that file doesn't exist yet, create it:

{
  "dependencies": {
    "@aria-plugins/aria-skills-marketplace": "latest"
  },
  "type": "module"
}

Then run:

cd ~/.config/opencode
bun install

3. Register the server plugin

Create ~/.config/opencode/plugins/marketplace.js with a single re-export:

export { default } from "@aria-plugins/aria-skills-marketplace";

4. Register the TUI plugin

Create (or update) ~/.config/opencode/tui.json:

{
  "plugin": ["@aria-plugins/aria-skills-marketplace"]
}

4. Set environment variables

export OPENCODE_MARKETPLACE_GITLAB_URL="https://gitlab.com/your-group/your-skills-registry"
export OPENCODE_MARKETPLACE_GITLAB_TOKEN="glpat-xxxxxxxxxxxx"

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.) to persist across sessions.
The GitLab token needs at minimum read_api scope.

5. Restart opencode

On the next start opencode will load the plugin, auto-update installed skills, and register the /aria-skills-marketplace command.

Usage

Type /aria-skills-marketplace in the opencode TUI to open the interactive marketplace:

AVAILABLE SKILLS
1. Git Commit Helper [v1.0.0] — Writes conventional commits [not installed]
2. Example Skill [v4.0.0] — A sample skill to demonstrate the marketplace [INSTALLED ✓]
3. Web Design Guidelines [v1.0.0] — Web design best practices [UPDATE AVAILABLE ↑1.1.0]

INSTALLED SKILLS
- example-skill v4.0.0 ✓
- web-design-guidelines v1.0.0 → update available (v1.1.0)

Enter a skill number or ID to install it, 'update all' to update all skills,
'remove <id>' to uninstall, or 'done' to exit.

Available AI tools

| Tool | Description | |------|-------------| | marketplace_status | Sync status + list of installed skills | | marketplace_list | Browse all registry skills (optional tag filter) | | marketplace_search | Search skills by keyword across name, description, and tags | | marketplace_install | Install a skill by ID | | marketplace_uninstall | Remove an installed skill | | marketplace_update | Update one skill or all skills with newer versions |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENCODE_MARKETPLACE_GITLAB_URL | Yes | Full HTTPS URL to the GitLab skills registry repo | | OPENCODE_MARKETPLACE_GITLAB_TOKEN | Yes | GitLab personal access token (read_api scope) |

GitLab Registry Structure

Your GitLab repository must follow this layout:

your-skills-registry/          ← the repo pointed to by OPENCODE_MARKETPLACE_GITLAB_URL
├── registry.json              ← root index listing all skills
└── skills/
    └── your-skill-id/
        ├── skill.json         ← skill manifest (id, version, tags, file list)
        ├── SKILL.md           ← AI instructions — required, must have frontmatter
        ├── references/        ← optional reference docs the AI reads
        ├── scripts/           ← optional helper scripts
        └── assets/            ← optional binary assets

registry.json — root index

Lists every skill available in the registry. Update this file whenever you add or version a skill.

{
  "version": "1",
  "updated": "2026-05-21T00:00:00Z",
  "skills": [
    {
      "id": "git-commit-helper",
      "name": "Git Commit Helper",
      "version": "1.2.0",
      "description": "Writes conventional commits and crafts perfect commit messages",
      "author": "your-username",
      "tags": ["git", "commits", "conventional-commits"],
      "path": "skills/git-commit-helper",
      "updatedAt": "2026-05-21T00:00:00Z"
    },
    {
      "id": "code-reviewer",
      "name": "Code Reviewer",
      "version": "2.0.1",
      "description": "Reviews pull requests and suggests improvements",
      "author": "your-username",
      "tags": ["code-review", "quality"],
      "path": "skills/code-reviewer",
      "updatedAt": "2026-04-10T00:00:00Z"
    }
  ]
}

| Field | Type | Description | |-------|------|-------------| | id | string | Unique slug — used as the folder name and install identifier | | name | string | Display name shown in the marketplace UI | | version | string | Semver version (e.g. 1.2.0) — must match skill.json | | description | string | One-line description shown in skill listings | | author | string | Author name or username | | tags | string[] | Searchable tags | | path | string | Path to the skill folder relative to the repo root | | updatedAt | string | ISO-8601 timestamp of the last update |

skill.json — skill manifest

Lives inside each skill folder. Declares metadata and the full list of files the installer should download.

{
  "id": "git-commit-helper",
  "name": "Git Commit Helper",
  "version": "1.2.0",
  "description": "Writes conventional commits and crafts perfect commit messages",
  "author": "your-username",
  "tags": ["git", "commits", "conventional-commits"],
  "license": "MIT",
  "files": {
    "skillMd": "SKILL.md",
    "references": [
      "references/conventional-commits.md",
      "references/examples.md"
    ],
    "scripts": [
      "scripts/validate-message.sh"
    ],
    "assets": []
  }
}

| Field | Type | Description | |-------|------|-------------| | id | string | Must match the folder name and registry.json entry | | name | string | Display name | | version | string | Semver version — bump this to trigger auto-updates | | description | string | Short description | | author | string | Author | | tags | string[] | Searchable tags | | license | string | Optional — SPDX license identifier | | files.skillMd | string | Relative path to the SKILL.md file (always "SKILL.md") | | files.references | string[] | Reference docs loaded alongside the skill | | files.scripts | string[] | Helper scripts bundled with the skill | | files.assets | string[] | Binary or static assets (images, data files, etc.) |

SKILL.md — AI instructions

Every skill must include a SKILL.md with YAML frontmatter. Without the frontmatter, opencode will not recognise the file as a skill and it will not appear in /skills.

---
name: git-commit-helper
description: Write conventional commits and craft perfect commit messages. Trigger when the user asks to commit, write a commit message, or needs git workflow help.
version: "1.2.0"
---

# Git Commit Helper

Full skill instructions go here. The AI reads this file when the skill is loaded.

## When to use me

- "help me commit these changes"
- "write a commit message"

## How I work

1. I examine your staged changes with `git diff --staged`
2. I suggest a conventional commit message
3. I confirm with you before running `git commit`

Frontmatter fields:

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Must match the skill id | | description | Yes | One sentence — what the skill does AND when to trigger it. Front-load the keywords a user is likely to say. | | version | No | Informational only |

Publishing a New Skill Version

1. Update version in skill.json (e.g. 1.2.0 → 1.3.0)
2. Update the matching version in registry.json
3. Update updatedAt in registry.json
4. Push to main

On the next opencode startup, the plugin detects the version bump and automatically installs the update. No user action required.

Building

# Install dev dependencies
npm install

# Build both bundles
npm run bundle

# Server plugin only
npm run bundle:server

# TUI plugin only
npm run bundle:tui

Output files:

• dist/marketplace.bundle.js — server plugin (copy to ~/.config/opencode/plugins/)
• dist/marketplace-tui.bundle.js — TUI plugin (loaded via tui.json)

License

MIT