Manage Aomi Skill

---
name: manage-aomi-skill
description: >
  Manage the aomi skill distribution pipeline. Trigger when the user asks about platform
  submission status, wants to push a skill update to a distribution channel, needs to add
  a new platform, wants to check staleness, or asks about any platform in _registry.yaml,
  including PR #679, PR #575, PR #21, issue #36, clawhub, codex-marketplace, agensi,
  lobehub, or anthropic submission.
version: "1.0"
author: aomi-labs
license: MIT
compatible-with: claude-code
allowed-tools: "Bash(./aomi-skill-manager.sh:*, git:*, python3:*, curl:*), Read, Edit, Grep"
permissions:
  files:
    read: [_registry.yaml, aomi-transact/SKILL.md, aomi-build/SKILL.md, distribution/, .worktrees/]
    write: [_registry.yaml, distribution/]
    deny_write: [aomi-transact/SKILL.md, aomi-build/SKILL.md]
  shell: [./aomi-skill-manager.sh, git, python3, curl]
  network:
    allow:
      - github.com
      - lobehub.com
      - skillsmp.com
      - agensi.io
      - www.agensi.io
      - clawhub.ai
      - wry-manatee-359.convex.site
      - claudemarketplaces.com
    deny: "*"
risk_tier: L1
requires:
  binaries: [git, python3]
  python_packages: [pyyaml]
---

# Manage Aomi Skill

## Overview

Manages distribution of `aomi-transact` and `aomi-build` across 14 platforms.
Three layers: (1) canonical SKILL.md files on `main`, (2) `_registry.yaml` as
machine-readable status tracker, (3) `./aomi-skill-manager.sh` CLI.

Platform types: `git-pr` (GitHub PR → `platform/*` branch + `.worktrees/*`),
`artifact` (form/upload → `distribution/*`), `cli-publish` (CLI tool → `distribution/*`),
`auto-index` (platform crawls GitHub), `self-hosted` (lives in this repo).

## When to Use

- Check platform status or install counts
- Push Grade A SKILL.md fixes to PR #679 (ccpi)
- Add a new distribution platform
- Check staleness after editing a canonical skill
- Update status after a PR merges or gets blocked
- Set up local worktrees for the first time

## Prerequisites

- `python3` + `pyyaml` (`pip3 install pyyaml`)
- `git` on PATH
- Run all commands from repo root (where `_registry.yaml` lives)

## Quick Start

```bash
./aomi-skill-manager.sh status          # all platforms at a glance
./aomi-skill-manager.sh setup           # create all git-pr worktrees
./aomi-skill-manager.sh stale           # which branches lag main
./aomi-skill-manager.sh check           # curl every URL with browser UA
cd $(./aomi-skill-manager.sh open ccpi) # jump into a platform worktree
```

## Instructions

**Check status:** `./aomi-skill-manager.sh status` — STALE? column shows how many
canonical commits each platform branch hasn't seen. `ok` = up to date.

**Fix blocked PR #679 (ccpi):**
```bash
./aomi-skill-manager.sh setup ccpi
./aomi-skill-manager.sh sync ccpi     # rebases Grade A fixes onto platform/ccpi
./aomi-skill-manager.sh diff ccpi     # verify changes
./aomi-skill-manager.sh push ccpi
./aomi-skill-manager.sh set-status ccpi open
./aomi-skill-manager.sh note ccpi "Grade A fixes pushed — awaiting re-review"
```

**After editing a canonical SKILL.md on main:**
```bash
./aomi-skill-manager.sh stale
./aomi-skill-manager.sh sync --all
```

**Add a new platform:**
```bash
./aomi-skill-manager.sh add smithery
./aomi-skill-manager.sh setup smithery
cd $(./aomi-skill-manager.sh open smithery)
# adapt files for the platform's schema
git add -p && git commit -m "feat: smithery platform variant"
cd - && ./aomi-skill-manager.sh push smithery
```

**Update state after external events:**
```bash
./aomi-skill-manager.sh set-status antigravity merged
./aomi-skill-manager.sh note clawhub "slug released — republishing"
```

**Check platform health (the canonical routine):**
```bash
./aomi-skill-manager.sh check            # every platform
./aomi-skill-manager.sh check lobehub    # one platform
```
**This is the only correct way to run routine checks.** Ad-hoc WebFetch
calls produce false-positive 403s on Cloudflare-fronted sites and
false-positive matches on loose substrings (e.g. "aomi" matches "Xiaomi"
in marketplace.json). The dispatcher reads each platform's `health_check:`
field and runs the correct probe per method. Stamps `last_checked` on
every platform after each run.

Methods (`health_check.method`):
- `http-200` — GET url(s) with browser UA; optional `needle:` regex must
  match; `needle_optional: true` lets indexing-pending platforms pass.
- `http-404` — GET url(s); 404 expected (inverted, for slug-availability
  on squatter-prone platforms).
- `gh-pr` — `gh pr view <pr> --json state,...`; OPEN/MERGED green, CLOSED yellow.
- `gh-issue` — `gh issue view <issue> --json state,...`.
- `marketplace-search` — fetch a JSON URL, regex-search the body for `needle:`.
- `npm-view` — `npm view <package> version`; non-empty result is green.
- `manual` — never auto-fails; just prints `reason:` text. Use for
  login-walled dashboards, deferred platforms, ready-to-submit zips.

**Pick needles that can't false-positive.** "aomi" matches "Xiaomi";
use `aomi-labs` or `aomi-transact`. For search pages whose `<input value>`
echoes the query, the needle must be something that only appears in
*result cards*, not the query echo (e.g. `aomi-labs/skills` for repo-link
result cards).

**Publish to a cli-publish platform (clawhub today):**
```bash
./aomi-skill-manager.sh publish clawhub aomi-transact --dry-run   # preview
./aomi-skill-manager.sh publish clawhub aomi-transact             # do it
./aomi-skill-manager.sh publish clawhub aomi-build
```
Reads `publish_paths.<slug>` and the platform's `cli:` from the registry,
coerces the SKILL.md frontmatter `version:` to semver (`0.10` → `0.10.0`),
runs the CLI from `/tmp` (clawhub bug: rejects relative-to-cwd paths),
then writes `published.<slug>` and `last_published` back into the registry.

**Verify slug availability on squatter-prone platforms (clawhub):**
```bash
./aomi-skill-manager.sh verify           # all `verify_urls` entries
./aomi-skill-manager.sh verify clawhub
```
For platforms with `verify_urls:` in the registry. Inverted semantics:
**404 = available (green), 200 = SQUATTED (red)**. Clawhub is a pure SPA
so the user-facing `/skills/<slug>` URL always returns 200 — `verify_urls`
points at the Convex HTTP API (`/api/v1/skills/<slug>`) which returns a
real 404 when the slug is unregistered.

## Examples

```bash
./aomi-skill-manager.sh status
./aomi-skill-manager.sh diff ccpi
./aomi-skill-manager.sh sync --all
./aomi-skill-manager.sh set-status codex-marketplace approved
./aomi-skill-manager.sh note agensi "install count: 3"
```

## Output

- `status` → colour table: platform / type / tier / status / staleness / blocker
- `stale` → platforms behind main with commit log
- `setup` → per-platform: exists / ok / skip
- `sync` → ok+synced or CONFLICT with recovery steps
- `diff` → standard git diff on skill files only
- `open` → worktree path for use with `cd $(...)`
- `check` → dispatches per-platform `health_check.method`; updates `last_checked`
- `verify` → per-`verify_urls` status with inverted semantics (404=available)
- `publish` → CLI publish + register version; `--dry-run` previews the resolved command

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `no _registry.yaml` | Wrong directory | `cd` to repo root |
| `pyyaml required` | Missing package | `pip3 install pyyaml` |
| `Branch not found` | setup not run | `./aomi-skill-manager.sh setup <name>` |
| `CONFLICT` on sync | Branch diverged | Follow printed recovery instructions |
| push rejected | No auth | Check `git remote -v`, ensure SSH/HTTPS auth |

## Safety Justification

Reads and writes `_registry.yaml` and `distribution/`. Does not modify canonical
`aomi-transact/SKILL.md` or `aomi-build/SKILL.md` (deny_write). Shell restricted to
`./aomi-skill-manager.sh`, `git`, `python3`, `curl`. Network restricted to the
seven platform hosts the `check` command verifies (GET-only via curl). Risk tier: L1.