JB shared preferred AI skill registry

jb-skill-preferences-setup.md

JB skill preferences setup and update

Use this file to install or update JB's preferred agent skills from the registry in this same Gist.

Registry

• Gist: https://gist.github.com/bjesuiter/98d5768dc360093affb8d8fdb064e45f
• Registry filename: jb-skill-preferences.json5
• Format: JSON5, not JSON

Requirements

• gh CLI installed and authenticated for reading Gists.
• npx available for the skills CLI.
• pi CLI available when installing Pi extensions.

Read the registry

gh gist view https://gist.github.com/bjesuiter/98d5768dc360093affb8d8fdb064e45f \
  --filename jb-skill-preferences.json5 \
  --raw

Parse it as JSON5, not strict JSON.

Recommended default: update this machine in ensure mode

Use ensure mode unless JB explicitly asks to prune or force-refresh.

Ensure mode means:

• install every entry listed in global.topics.core
• do not delete locally installed skills that are not in the registry
• do not install global.topics.experimental unless explicitly requested
• treat repeated installs as acceptable/idempotent unless the CLI reports otherwise

Install order:

1. Install global.topics.core.piExtensions globally:

   pi install <source>

2. Install global.topics.core.skills globally with npx -y skills add. Use the topic's install.skillsCliDefaultArgs if present, otherwise schema.defaultSkillsCliArgs.

   Expansion rules:

   • skill: "name" becomes --skill name
   • skills: ["a", "b"] becomes repeated --skill a --skill b
   • skill: "*" with wildcard: true becomes --skill '*'
   • entry with only source installs the source without --skill
   • skillsCliExtraArgs: [...] appends those exact extra args for that entry, e.g. OpenClaw risk acknowledgement flags

3. Continue after individual failures, record failed sources, and report them at the end.

New-entry workflow: install exactly the skill just added

Use this workflow when JB adds a new skill to jb-skill-preferences.json5 and then says to install it.

Do not run full ensure mode in this situation unless JB asks for it. Install exactly the newly added registry entry using the same install rules.

Workflow:

1. Identify the exact entry that was just added or changed in the registry.

   • Prefer the entry from the current conversation/diff.
   • If unclear, compare the before/after registry or ask JB which entry to install.

2. Determine scope from where the entry was added:

   • global.topics.*.skills → global skills CLI install using that topic's install args, or schema.defaultSkillsCliArgs.
   • global.topics.*.piExtensions → pi install <source>.
   • project.topics.*.skills → project-local skills CLI install; omit -g unless the topic overrides it.
   • project.topics.*.piExtensions → pi install -l <source>.

3. Install only that entry:

   • skill: "name" → install only that skill.
   • skills: ["a", "b"] → install exactly those listed skills from that entry.
   • skill: "*", wildcard: true → install that wildcard entry only.
   • source only → install that source only.

4. Do not install sibling entries from the same topic unless JB explicitly asks.

5. Verify the expected skill(s) are present, then report the exact command(s) run and any failures.

Optional mode: include experimental

Only if JB asks for experimental skills, also install global.topics.experimental using the same rules.

Do not install experimental by default.

Optional mode: force refresh

Use force refresh when JB asks to update/reinstall existing local skills from upstream.

Workflow:

1. Run ensure mode first.

2. If the skills CLI supports an overwrite/force/update flag, use it. Check current CLI help rather than guessing:

   npx -y skills add --help

3. If no safe force flag exists, reinstall with normal skills add and report that refresh depth depends on the CLI's update semantics.

4. For Pi extensions, rerun pi install <source> and report any extension-specific failures.

Optional mode: prune stale registry-managed skills

Only prune when JB explicitly asks.

Prune mode means removing local skills that were previously installed from this preference registry but are no longer listed.

Guardrails:

• Never delete arbitrary local skills just because they are absent from the registry.
• Before deleting, show a removal plan and ask for confirmation.
• Prefer pruning only skills with names that clearly belong to a registry-managed source/topic.
• Do not touch canonical repo skills under skills/<name>/ in this repository.
• For this skills repo, cleanup test installs under .agents/skills/ after validation.

Useful inspection commands:

find ~/.agents/skills ~/.pi/agent/skills -maxdepth 2 -name SKILL.md 2>/dev/null
find .agents/skills -maxdepth 2 -name SKILL.md 2>/dev/null

Project topic install

If asked for a project topic, prefer project.topics.<topic> and use project-local scope:

• Pi extensions:

  pi install -l <source>

• Skills CLI: omit -g unless the topic overrides it.

• Merge local skills, prompts, or extensions arrays into .pi/settings.json without removing unrelated settings.

• Warn before writing personal absolute paths into a shared repo.

• After .pi/settings.json or Pi extension changes, tell JB to run /reload or restart Pi.

Validate registry and local install state

Use this workflow when JB asks to validate preferred skills, check whether registry skills are installed, or verify that local installed skills are up to date enough without pruning.

Validation is read-mostly. Do not delete or prune anything. Do not install missing project/experimental skills unless JB explicitly asks.

Validation levels:

1. Registry parse validation

   • Fetch jb-skill-preferences.json5 from this Gist.
   • Parse it as JSON5.
   • Confirm top-level global and project sections exist.
   • Confirm wildcard entries use skill: "*" plus wildcard: true.

2. Source validity validation

   • For each unique skills[].source, run:

     npx -y skills add <source> --list

   • For sources that require special acknowledgement, such as OpenClaw community sources, report the blocked source and the required flag instead of silently accepting risk.

   • If JB explicitly allows OpenClaw risk validation, rerun with the CLI-provided acknowledgement flag, e.g. --dangerously-accept-openclaw-risks.

3. Registry-entry availability validation

   • For every explicit skill: "name" or skills: [...] entry, confirm the listed skill name appears in that source's --list output.
   • For skill: "*", wildcard: true, confirm the source lists skills; do not require a fixed set.
   • For source-only entries, confirm the source lists at least one installable skill.

4. Local install validation

   • Inspect installed local/global skill dirs:

     find ~/.agents/skills ~/.pi/agent/skills -maxdepth 2 -name SKILL.md 2>/dev/null | sort

   • By default, require global.topics.core explicit skills to be installed locally.

   • Treat global.topics.experimental and all project.topics.* skills as optional unless JB asked to validate those topics specifically.

   • Report missing optional skills separately from missing core skills.

5. Up-to-date check

   • A strict up-to-date check is only possible by rerunning install/ensure mode or comparing installed files with freshly fetched source files.
   • For normal validation, report whether each source is reachable and each expected skill is present.
   • If JB asks to make skills up to date, run ensure mode for global.topics.core or the requested exact topic/entry.

Validation report format:

• Registry parse: pass/fail
• Source validity: pass/fail with failed sources
• Entry availability: missing or mismatched entries
• Local core install: installed/missing
• Optional experimental/project entries: installed/missing, clearly marked optional
• Actions taken: validation-only, ensure run, or skipped installs

Verification after install/update

After ensure/refresh mode:

1. Report installed sources and failures.

2. Spot-check expected skill directories/files:

   find ~/.agents/skills ~/.pi/agent/skills -maxdepth 2 -name SKILL.md 2>/dev/null | sort

3. If working inside the bjesuiter/skills repo, run discovery and then cleanup test installs:

   npx skills add . --list
   npx skills add . --skill <changed-skill> -a codex -y
   rm -rf .agents/skills/<changed-skill>

4. Tell JB whether this was:

   • ensure-only
   • force-refresh attempted
   • experimental included
   • prune attempted/completed

Command examples

Single skill:

npx -y skills add -g bjesuiter/skills --skill jb-tdd --agent codex opencode pi -y

Multiple skills from one source:

npx -y skills add -g bjesuiter/skills --skill jb-adr --skill jb-tdd --agent codex opencode pi -y

Wildcard source:

npx -y skills add -g mattpocock/skills --skill '*' --agent codex opencode pi -y

Source without explicit skill:

npx -y skills add -g remorses/playwriter --agent codex opencode pi -y

Pi extension:

pi install npm:@tmustier/extending-pi

Guardrails

• Preserve jb-skill-preferences.json5; do not rewrite it unless explicitly updating preferences.
• Do not invent alternate registry filenames.
• Keep global and project semantics separate.
• Default to ensure mode, not prune mode.
• Never prune without confirmation.
• After installing Pi extensions or project-local settings, restart Pi or run /reload if needed.

jb-skill-preferences.json5

{
  version: 1,
  schema: {
    emptyArrays: "omit",
    wildcardSemantics: "wildcard: true means intentionally install all current and future skills from source",
    defaultSkillsCliArgs: ["-g", "--agent", "codex", "opencode", "pi", "-y"],
  },
  global: {
    topics: {
      core: {
        description: "Always-installed general productivity skills and Pi extensions.",
        piExtensions: [
          "npm:@tmustier/pi-tab-status",
          "npm:@tmustier/extending-pi",
          "https://github.com/hazat/glimpse",
          "https://github.com/badlogic/pi-diff-review",
          "npm:@plannotator/pi-extension",
          "https://github.com/mitsuhiko/pi-draw",
          "https://github.com/nicobailon/pi-side-chat",
          "https://github.com/fluxgear/pi-thinking-steps",
          "https://github.com/FredySandoval/pi-runcat",
          "npm:pi-openai-service-tier",
          "https://github.com/capyup/pi-goal",
          "https://github.com/b3-business/titanbase-provider",
        ],
        cli: [
          {
            name: "vacant",
            source: "https://github.com/skorfmann/vacant",
            install: "go install github.com/skorfmann/vacant@latest",
            description: "Domain availability checker CLI.",
          },
        ],
        skills: [
          {
            source: "bjesuiter/skills",
            skills: [
              "jb-adr",
              "jb-beans",
              "jb-beansloop",
              "jb-bgproc",
              "jb-browser-testing",
              "jb-chrome-mcp",
              "jb-committer",
              "jb-docs-scraper",
              "jb-markit",
              "jb-refine-code",
              "jb-skill-prefs",
              "jb-tdd",
              "jb-worktree",
              "mcporter",
              "mole-mac-cleanup",
              "nb",
              "security-check",
              "summarize",
            ],
          },
          { source: "Forward-Future/loop-library", skill: "loop-library" },
          { source: "ascorbic/bgproc", skill: "bgproc" },
          { source: "vercel-labs/agent-browser", skill: "agent-browser" },
          { source: "heredotnow/skill", skill: "here-now" },
          { source: "https://github.com/Martian-Engineering/pagedrop.git", skill: "pagedrop" },
          { source: "bholmesdev/skills", skills: ["alt-text", "simplify"] },
          /*
           * repo: https://github.com/mattpocock/skills
           * extracted: 2026-05-16T15:55:00Z
           * wildcard tracks all current and future skills. Current discovered skills:
           *   - design-an-interface
           *   - qa
           *   - request-refactor-plan
           *   - ubiquitous-language
           *   - diagnose
           *   - grill-with-docs
           *   - improve-codebase-architecture
           *   - prototype
           *   - setup-matt-pocock-skills
           *   - tdd
           *   - to-issues
           *   - to-prd
           *   - triage
           *   - zoom-out
           *   - review
           *   - writing-beats
           *   - writing-fragments
           *   - writing-shape
           *   - git-guardrails-claude-code
           *   - migrate-to-shoehorn
           *   - scaffold-exercises
           *   - setup-pre-commit
           *   - edit-article
           *   - obsidian-vault
           *   - caveman
           *   - grill-me
           *   - handoff
           *   - write-a-skill
           */
          { source: "mattpocock/skills", skill: "*", wildcard: true },
          { source: "steipete/agent-scripts", skills: ["video-transcript-downloader", "skill-cleaner"] },
          { source: "remorses/playwriter" },
          { source: "tyler6204/openclaw-maintainer-skill", skill: "openclaw-maintainer" },
          { source: "openclaw/Peekaboo", skill: "peekaboo", skillsCliExtraArgs: ["--dangerously-accept-openclaw-risks"] },
        ],
        install: {
          skillsCliDefaultArgs: ["-g", "--agent", "codex", "opencode", "pi", "-y"],
          piInstallScope: "global",
        },
        notes: "Initial registry generated from ~/jb-home/AGENTS.md Tracked Skills. Install skills CLI entries globally with npx -y skills add -g <source> --skill <skill> --agent codex opencode pi -y unless an entry specifies cli: skills@latest or omits skill. Install piExtensions globally with pi install <source>; these are Pi coding-agent-specific and intentionally not generic packages.",
      },
      experimental: {
        description: "Trial area for skills and Pi extensions that may not be kept long term.",
        reviewAfter: "2026-08-08",
        skills: [
          /*
           * repo: https://github.com/alexknowshtml/api2cli
           * extracted: 2026-05-08T12:35:49Z
           * installs:
           *   - api2cli
           */
          { source: "alexknowshtml/api2cli", skill: "*", wildcard: true },
          // Original upstream kept for reference:
          // { source: "nicobailon/visual-explainer", skill: "visual-explainer" },
          { source: "https://github.com/bjesuiter/visual-explainer/tree/add-glimpse-support", skill: "visual-explainer" },
          { source: "bjesuiter/skills", skill: "sweetlink" },
          { source: "stephenturner/skill-deslop", skill: "deslop" },
          /*
           * repo: https://github.com/JuliusBrussee/caveman
           * extracted: 2026-05-08T12:35:49Z
           * installs:
           *   - caveman
           *   - caveman-compress
           *   - cavecrew
           *   - caveman-commit
           *   - caveman-help
           *   - caveman-review
           *   - caveman-stats
           *   - compress
           */
          { source: "JuliusBrussee/caveman", skill: "*", wildcard: true },
          { source: "anthropics/claude-code", skill: "frontend-design" },
          { source: "steipete/agent-scripts", skill: "nano-banana-pro" },
          { source: "steipete/agent-scripts", skill: "openai-image-gen" },
          { source: "steipete/agent-scripts", skill: "browser-use" },
          /*
           * repo: https://github.com/Leonxlnx/taste-skill
           * extracted: 2026-05-08T12:35:49Z
           * installs:
           *   - brandkit
           *   - industrial-brutalist-ui
           *   - gpt-taste
           *   - image-to-code
           *   - imagegen-frontend-mobile
           *   - imagegen-frontend-web
           *   - minimalist-ui
           *   - full-output-enforcement
           *   - redesign-existing-projects
           *   - high-end-visual-design
           *   - stitch-design-taste
           *   - design-taste-frontend
           */
          { source: "Leonxlnx/taste-skill", skill: "*", wildcard: true },
          /*
           * repo: https://github.com/av/facts
           * extracted: 2026-05-08T14:05:00Z
           * installs:
           *   - facts
           *   - facts-discover
           *   - facts-implement
           *   - facts-refine
           */
          { source: "https://github.com/av/facts", skill: "*", wildcard: true },
          { source: "mattpocock/skills", skill: "teach" },
          { source: "https://github.com/mattpocock/skills/tree/main/skills/in-progress/review", skill: "review" },
        ],
        piExtensions: [
          "npm:pi-fff",
          "https://github.com/davebcn87/pi-autoresearch",
          "https://github.com/nicobailon/pi-interactive-shell",
          "https://github.com/nicobailon/pi-subagents",
          "https://github.com/nicobailon/pi-intercom",
          "https://github.com/nicobailon/pi-messenger",
          "https://github.com/nicobailon/pi-review-loop",
          "https://github.com/nicobailon/pi-web-access",
          "https://github.com/earendil-works/pi-review",
        ],
        notes: "Global trial area for skills and Pi extensions that may not be kept long term.",
      },
    },
  },
  project: {
    topics: {
      serviceDev: {
        description: "Project-local service deployment and infrastructure skills.",
        skills: [
          { source: "railwayapp/railway-skills", skill: "use-railway" },
        ],
        notes: "Install for projects that deploy or manage Railway services.",
      },
      webDev: {
        description: "Project-local web development Pi extensions.",
        piExtensions: [
          "https://github.com/nicobailon/pi-annotate",
        ],
        notes: "Install for web development projects that need browser/page annotation workflows.",
      },
      slidedeckDev: {
        description: "Project-local slide deck and visual decision presentation Pi extension.",
        piExtensions: [
          "https://github.com/nicobailon/pi-design-deck",
        ],
        notes: "Install for projects that need design-deck slide decks for architecture, UI, or code decisions.",
      },
      selfLearning: {
        description: "Project-local self-learning Pi extensions.",
        piExtensions: [
          "npm:pi-self-learning",
        ],
        notes: "Install only in projects where self-learning is explicitly wanted.",
      },
      devLibs: {
        description: "Project-local library/framework helper skills.",
        skills: [
          { source: "open-circle/agent-skills", skills: ["formisch", "valibot"] },
        ],
        notes: "Project-local development library skills for form and schema validation.",
      },
      openclawDev: {
        description: "Project-local OpenClaw maintainer and related agent automation skills.",
        skills: [
          { source: "tyler6204/openclaw-maintainer-skill", skill: "openclaw-maintainer" },
          { source: "steipete/agent-scripts", skills: ["agent-transcript", "openclaw-relay"] },
        ],
        notes: "Install for OpenClaw maintainer projects that need the maintainer workflow plus Peter's OpenClaw relay skill.",
      },

      evlog: {
        description: "Project-local evlog adoption, logging review, audit logs, and log analysis skills.",
        skills: [
          {
            source: "https://www.evlog.dev",
            skills: [
              "review-logging-patterns",
              "build-audit-logs",
              "analyze-logs",
            ],
          },
        ],
        notes: "Install for projects adopting evlog wide events, structured errors, tamper-aware audit trails, or .evlog/logs analysis.",
      },
      appleDev: {
        description: "Project-local Apple platform, ASC, Xcode, and SwiftUI skills.",
        skills: [
          {
            source: "Dimillian/Skills",
            skills: [
              "app-store-changelog",
              "ios-debugger-agent",
              "macos-spm-app-packaging",
              "swift-concurrency-expert",
              "swiftui-liquid-glass",
              "swiftui-performance-audit",
              "swiftui-ui-patterns",
              "swiftui-view-refactor",
            ],
          },
          /*
           * repo: https://github.com/rudrankriyam/app-store-connect-cli-skills
           * extracted: 2026-05-08T12:35:49Z
           * installs:
           *   - asc-app-create-ui
           *   - asc-aso-audit
           *   - asc-build-lifecycle
           *   - asc-cli-usage
           *   - asc-crash-triage
           *   - asc-id-resolver
           *   - asc-localize-metadata
           *   - asc-metadata-sync
           *   - asc-notarization
           *   - asc-ppp-pricing
           *   - asc-release-flow
           *   - asc-revenuecat-catalog-sync
           *   - asc-screenshot-resize
           *   - asc-shots-pipeline
           *   - asc-signing-setup
           *   - asc-submission-health
           *   - asc-subscription-localization
           *   - asc-testflight-orchestration
           *   - asc-wall-submit
           *   - asc-whats-new-writer
           *   - asc-workflow
           *   - asc-xcode-build
           */
          { source: "rudrankriyam/app-store-connect-cli-skills", skill: "*", wildcard: true },
          { source: "steipete/agent-scripts", skill: "native-app-performance" },
          { source: "bjesuiter/skills", skill: "xcode" },
        ],
        notes: "Project-local Apple development skills from Dimillian/Skills, App Store Connect CLI skills, and native Apple app performance tooling.",
      },
    },
  },
}