abi-skills — ABI codebase health and skill synchronization

Use this skill for bounded, reviewable improvement cycles across the ABI repository, its canonical skills, the 16 bundled ABI plugin fixtures, and the local ABI Mega Codex plugin.

Sources of truth

• Repository instructions: AGENTS.md, then tasks/lessons.md and tasks/todo.md.
• Stable 1.99.1 pin: rust-toolchain.toml and .github/workflows/ci.yml must agree.
• Repository-specific skills: .agents/skills/. This portable abi-skills text is synchronized there from ~/.grok/skills/abi-skills/SKILL.md under the live ~/.grok/sync-targets.json catalog.
• Repository mirrors: tracked .claude/skills/ plus an optional ignored .grok/, synchronized by .agents/skills/sync-clis/launch.sh. A fresh Git worktree has no .grok/ because Git does not materialize ignored files. The long-lived main checkout does have it (69 skill directories observed 2026-08-22), so the launcher targets two mirrors there and only .claude/skills/ in a fresh worktree. This checkout-local difference is one reason mirror sync must run from the stable main checkout.
• OpenCode: .opencode/skills is a symlink to .agents/skills.
• Codex home skills: ~/.codex/skills/<name>/SKILL.md are installed explicitly.
• ABI bundled plugins: 16 build-time fixtures under crates/abi-plugins/plugins/ (including tui-plugin); verify manifest, registry, and runtime-dispatch agreement with .agents/skills/plugin-runtime-tester/plugins.sh.
• ABI Mega source: ~/dev/active/plugins/abi-mega/, restored on 2026-09-28 and verified present on 2026-10-02. Recheck the source and script paths before running them; marketplace registration alone does not prove that the current version is installed.
• Live Rust pin: read repo-root rust-toolchain.toml. Always use ./tools/cargo.sh (Homebrew stable cargo may shadow the selected rustup toolchain).

Two traps that have already cost a session

This portable skill has two synchronization layers. As verified on 2026-10-02, catalog.portableSkills in ~/.grok/sync-targets.json includes abi-skills. Its central source is ~/.grok/skills/abi-skills/SKILL.md; the central driver projects that text into ABI's .agents/skills/ and the declared home targets. Editing only a target can be overwritten by the SessionEnd sync. Read the live manifest and compare source/target bytes before a correction, preserve existing bytes, then correct the central source and review the driver's dry-run before applying. --targets limits targets, not skill names: reject unrelated pending writes rather than assuming a run touches only this skill.

ABI's separate launcher then mirrors .agents/skills/ into the repository's .claude/skills/ and .grok/ surfaces. The installed ~/.config/ollama/skills/abi-skills/SKILL.md is outside the live target list as of 2026-10-02; preserve its bytes and update it explicitly when needed. Older pre-rewrite home copies and manual-copy advice are historical. Do not reintroduce .zigversion, ./build.sh check-parity, or src/plugins/.

Do not run sync-clis/launch.sh from a worktree. The launcher stamps an absolute Base directory for this skill: <checkout>/.claude/skills/<name> line into each mirrored SKILL.md, so the mirror content depends on which checkout produced it. Run from a worktree it rewrites those lines to the worktree path (measured 2026-08-22: 5 files — codebase-analysis, modern-patterns, and the three refactor-* skills), and committing that points every mirror at a directory that disappears when the worktree is removed. Sync from the main checkout, or revert any file whose only diff is that line.

An abi worktree must be created as a sibling of the canonical checkout. Cargo.toml reaches the substrate through relative paths (../wdbx/crates/…), so a worktree placed anywhere else resolves them to nothing and cargo fails with no matching package named abi-compute — an error that names the consumer and reads as a broken repository. The canonical checkout is /Users/donald/sources/repos/abi, so /Users/donald/sources/repos/abi-wt-<topic>-<date>/ satisfies it. For the same reason, git fetch && git status in abi, abbey, and wdbx before believing any cargo error in any of them: a stale sibling breaks the other two, and the default build hides it because both deps are optional.

The retired root src/ implementation tree is fully absent. Do not recreate the Zig-era tree as a health check. The live Rust fixtures are crates/abi-plugins/plugins/ and must remain in manifest/compile-time/runtime parity.

Skill Loop

Skill Loop is the optional npm package under the stylusnexus scope named skill-loop-cli, pinned to version 0.3.3 (declared in repo .mcp.json / opencode.json). A missing bare skill-loop command is expected on hosts without a global install. Prefer the one-shot form (package + pin via env so scanners do not treat the npm locator as a repo path):

SKILL_LOOP_PKG="@stylusnexus/skill-loop-cli"
SKILL_LOOP_VER="0.3.3"
npx -y -p "${SKILL_LOOP_PKG}@${SKILL_LOOP_VER}" skill-loop <command>

The relevant commands are:

Need	Command
Build or refresh the registry	skill-loop init
Show health	skill-loop status
Inspect stale content and references	skill-loop inspect
Log this workflow	skill-loop log abi-skills <outcome>

There is no skill-loop scan command. Counts and broken-reference totals are live telemetry, not durable capability claims.

Workflow

1. Freeze the target — inspect git status --short --branch, git worktree list --porcelain, branches, stashes, and remotes. If another process moves the checkout, stop and use an isolated worktree.
2. Select the toolchain locally — use ./tools/cargo.sh for all ABI gates (Homebrew stable cargo may shadow the selected rustup toolchain).
3. Establish a baseline — run ./tools/check.sh non-interactively. Build abi-cli explicitly before user-facing smoke so the executable being tested is current and the evidence names the binary-producing command.
4. Refresh ABI Mega evidence:
   • ~/dev/active/plugins/abi-mega/skills/abi-goal-orchestrator/scripts/refresh-inventory.sh
   • ~/dev/active/plugins/abi-mega/skills/abi-markdown-auditor/scripts/scan-markdown.sh
5. Inspect skills — run Skill Loop init, status, and inspect when the npm tool is available; otherwise perform a targeted manual reference audit.
6. Fix a bounded slice — repair actionable stale paths or false claims. Preserve template placeholders and intentionally external references.
7. Verify plugins — run .agents/skills/plugin-runtime-tester/plugins.sh; do not infer runtime dispatch from registry listing alone.
8. Synchronize in source order — preview the central driver with python3 ~/.grok/scripts/sync-clis.py --dry-run --targets abi,agents,claude,codex. Apply only reviewed projections, then require a second run to report 0 actions/changes. Preview .agents/skills/sync-clis/launch.sh --dry-run from this canonical checkout before running its repository mirror pass. The dry-run prints would sync: for every canonical skill whether or not its mirror differs (measured 2026-09-04: a full would sync list, zero new git status entries after the real run). Judge change by diffing git status --porcelain before and after, not by the preview list.
9. Verify installed skill text — compare the central source with the managed ABI/Agents/Claude/Codex targets and repository mirrors. Preserve and explicitly update an installed Ollama copy while it remains outside the manifest. Companion-resource parity follows the source projection contract; destination-only support entries remain preserved.
10. Validate — run ./tools/check.sh once (it already contains fmt, clippy, build, tests, and docs; the older form listed it twice and named clippy separately) plus .agents/skills/docs-validate/validate.sh. Rebuild with ./tools/cargo.sh build -p abi-cli only if a smoke step replaced the binary.
11. Log — skill-loop log abi-skills success (or partial/failure) when telemetry is initialized.
12. Integrate — commit on the default branch in this canonical checkout, per AGENTS.md Git Workflow; a branch or PR only when isolation is genuinely required or requested (the older cursor/-branch rule here contradicted that policy; corrected 2026-09-04). Never force-push main. Re-inventory immediately before merge and cleanup.

ABI Mega refresh

~/dev/active/plugins/abi-mega/skills/abi-goal-orchestrator/scripts/refresh-inventory.sh \
  "$PWD" ~/dev/active/plugins/abi-mega/assets/abi-current-inventory.md
~/dev/active/plugins/abi-mega/skills/abi-markdown-auditor/scripts/scan-markdown.sh \
  "$PWD" ~/dev/active/plugins/abi-mega/assets/abi-markdown-audit.md

These commands refresh local plugin assets. They do not install or upgrade the Codex plugin. Confirm the source manifest version and installed-plugin state separately through Plugin Management.

Validation commands

The central sync regressions run through ./tools/check.sh policy-test discovery, or independently:

python3 -m unittest discover -s tools/tests -p test_sync_clis.py -v

They execute the installed ~/.grok/scripts/sync-clis.py with a synthetic 12-target manifest and temporary sources, destinations, home, and logs. The second complete run must report 0 actions/changes and preserve managed bytes, entry types, inode identities, and modification times. Dry-run and apply must agree on pending actions. Run logs are intentionally refreshed and excluded from the managed-file comparison. The installed manifest is also checked read-only for source and native agent destinations.

The current central contract preserves destination-only support entries even when a source file diverges; a conflicting entry is replaced individually. Task agents are rendered for Codex TOML, Claude Markdown, and OpenCode Markdown; Codex memories and the global charter are not task-agent destinations. This supersedes the earlier whole-tree replacement and Codex-only persona wording. The source remains ~/.grok/skills with the bundled personas and roles.

Hosts without the central driver explicitly skip these integration tests; the manifest check also skips when its file is absent. A skipped suite is not sync evidence. The tests do not vendor the driver or run synchronization against live CLI targets. ABI's separate mirror launcher retains its existing behavior.

./tools/check.sh                                # full gate: fmt, clippy, build, tests, docs
.agents/skills/plugin-runtime-tester/plugins.sh # registry + run dispatch, all 16 fixtures
.agents/skills/docs-validate/validate.sh
./tools/cargo.sh build -p abi-cli               # only if a smoke step replaced the binary

Commands that no longer exist. ./build.sh check-parity and ./build.sh lint both exit 2 with unknown target (measured 2026-08-22). build.sh is a compatibility shim that forwards only check, cli, mcp, test, and fmt; ./build.sh -l lists what it actually accepts. Any .zigversion or ~/.zvm/$(cat .zigversion) PATH prefix is dead — the file does not exist after the Rust rewrite.

Run ./tools/check.sh non-interactively as a matter of habit, but do not justify it with the old dashboard-smoke reason. Verified 2026-08-22: check.sh invokes no TUI step at all — it covers toolchain versions, repository policy tests, the Abbey contract corpus, Rust source-size limits, fmt, clippy, build, tests, Metal/CUDA device features, benchmark regression, and docs. A PTY does not invalidate it. The interactive-mode hazard is real, but it belongs to the TUI surfaces check.sh never calls — .agents/skills/dashboard-smoke/dashboard.sh and tools/run_tui_smoke.sh. Run those non-interactively.

Capture gate results by redirecting to a file and echoing $? from the command itself. Piping to tail reports tail's exit status and has manufactured a false green on this machine before.

Claim boundaries

• The 16 bundled plugins are build-time Rust modules, not sandboxed marketplace extensions or hot-reloadable code.
• Registry presence does not prove plugin run dispatch; use the runtime tester.
• Marketplace registration does not prove ABI Mega is installed or current.
• Skill Loop reports scanner findings that require review; a count alone does not prove every reference is actionable or broken. In the 2026-08-22 inspection, the two abi-skills "broken references" were the contextual prose basenames sync-clis/launch.sh and SKILL.md, not missing workflow files. On 2026-09-04 Skill Loop flagged 13; a manual audit of every path-like token in this file against the repository root found 45 references, 11 unresolved, and all 11 were prose basenames (check.sh, SKILL.md), the /sync-clis command name, the cursor/ prefix, worktree placeholders, or paths this file itself describes as dead (src/plugins/, the .zigversion prefix). Zero were actionable. The detector also resolves companion references such as references/claim-boundaries.md against the wrong root.