agent-skills/README.md

# agent-skills

Reusable skill library for AI coding delegates (session Claude, kimi, agy,
vibe, codex) working on the CloudHost/iWP.es projects. Goal: capture
process knowledge once, so a delegate brief can reference a skill instead
of re-explaining the same process from scratch every time.

## Format

Each skill is a directory under `skills/` containing a `SKILL.md` with
YAML frontmatter (`name`, `description`, optional `license`/`source`)
followed by the actual instructions in markdown. This is the same format
Claude Code's native `Skill` tool consumes directly, and matches the
convention used by other cross-platform skill projects (see Provenance
below) -- Gemini CLI's `activate_skill` tool and some Codex plugin setups
can potentially consume the same format natively, though that hasn't
been separately verified for this repo yet.

**For delegates that don't natively discover skills** (kimi, vibe, and
any codex/agy invocation not specifically configured for plugin
discovery): read the relevant `SKILL.md` yourself before writing the
delegate's brief, and fold its content into the prompt directly rather
than assuming the delegate can fetch it itself.

## Skills in this repo

- `wordpress-plugin-rebrand` -- forking/rebranding an existing WP plugin
  under a new brand prefix.
- `wordpress-plugin-conventions` -- baseline WP plugin coding standards.
- `wordpress-cli-remote-execution` -- running wp-cli against a site inside
  a remote jail/container.
- `gitea-release-workflow` -- tagging releases on self-hosted Gitea,
  including a real release-asset-unreachable gotcha and its workaround.
- `bastille-jail-provisioning` -- FreeBSD jail creation via clone-from-base,
  including a real recurring IP-conflict gotcha.
- `remote-shell-quoting-safety` -- the base64-push pattern for landing
  `$`/quote-heavy content through nested shell layers without corruption.
- `server-fleet-map` -- which host is for what (dev/corporate/affiliate/
  customers) and how to decide where new work belongs.
- `delegate-brief-writing` -- what a self-contained brief for a memoryless
  CLI delegate needs to contain.
- `verification-before-completion` -- never relay a delegate's self-report
  as fact; how to actually re-verify.
- `karpathy-guidelines` -- general LLM-coding behavioral guidelines
  (simplicity, surgical changes, surfacing assumptions).
- `web-design-best-practices` -- modern UI/UX conventions to apply by
  default (typography, spacing, color/contrast, motion, forms).
- `web-accessibility` -- WCAG-aligned baseline (semantic HTML, keyboard
  nav, contrast, ARIA usage, forms).
- `security-headers-and-tls` -- HTTP security headers and TLS/SSL
  configuration strength, including reverse-proxy-layer gotchas.
- `code-sanitization` -- framework-agnostic injection-prevention baseline
  (SQLi, XSS, command injection, path traversal, uploads, deserialization).
- `parallel-delegate-shared-files` -- never have 2+ parallel delegates edit
  the same bootstrap/wiring file; use self-registration instead. Real
  incident from the iWP Cache build (lost updates, twice).
- `wordpress-plugin-staging-verification` -- use the persistent
  `staging1` jail (real-world plugin set left active) for verifying new
  plugins, not a disposable clean-room jail; includes the full
  cache-plugin verification checklist and cosmetic-vs-real error gotchas.
- `jail-dedicated-subnet-migration` -- move jails from shared-IP-on-LAN
  aliasing to a dedicated private VNET subnet, eliminating ARP collisions
  with other physical LAN devices. Full bridge/NAT/pf setup, VNET jail
  creation syntax, and a content-preserving migration procedure (DB grant
  re-scoping, hairpin-NAT non-issue, cache-HIT-hides-DB-failures gotcha).
- `linus-torvalds-code-review` -- emulates Linus Torvalds' code-review
  method (triggers, precedence hierarchy, voice/tone), distilled from
  38,293 real review moves across two decades of Linux kernel mailing
  list emails. This is the clean variant (no profanity). The upstream
  project also ships a "soul" persona variant that replicates Torvalds'
  actual (profane) tone -- deliberately not installed here; see
  [Mte90/linus-torvalds-skill](https://github.com/Mte90/linus-torvalds-skill)
  directly if that's ever wanted instead.
- `code-review` -- two-axis review (Standards + Spec) of a diff against a
  fixed point, run as parallel sub-agents so neither axis masks the other.
- `codebase-design` -- shared vocabulary for designing deep modules
  (interface, seam, depth, adapter, leverage, locality) and applying the
  deletion test.
- `diagnosing-bugs` -- disciplined loop for hard bugs and regressions:
  build a tight feedback loop, reproduce, minimise, hypothesise,
  instrument, fix, then post-mortem.
- `full-output-enforcement` -- override default LLM truncation; ban
  placeholder comments and partial outputs, and handle long outputs
  cleanly.
- `handoff` -- compact the current conversation into a portable document
  so another agent can continue the work.
- `redesign-existing-projects` -- audit an existing UI for generic AI
  patterns, then upgrade it piece by piece without rewriting the stack.
- `research` -- delegate reading legwork to a background agent against
  primary sources, and capture cited findings as a Markdown file.
- `resolving-merge-conflicts` -- resolve an in-progress git merge or
  rebase conflict by tracing each side's intent; never `--abort`.
- `tdd` -- red-green-refactor test-driven development, one vertical slice
  at a time, at pre-agreed seams.

## Provenance

Some skills here are original (derived directly from real incidents on
this project); some are adapted from external open-source skill
libraries under their original license, with attribution kept in
each skill's frontmatter:
- [obra/superpowers](https://github.com/obra/superpowers) (MIT)
- [SuperClaude-Org/SuperClaude](https://github.com/SuperClaude-Org/SuperClaude_Framework) (MIT)
- andrej-karpathy-skills (MIT)
- [Mte90/linus-torvalds-skill](https://github.com/Mte90/linus-torvalds-skill) (CC0-1.0)
- [mattpocock/skills](https://github.com/mattpocock/skills) (MIT)
- [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) (MIT)

## Vetting external skills

Before installing a skill from an external repo, run NVIDIA
[SkillSpector](https://github.com/NVIDIA/SkillSpector) against it with
`--no-llm` (static analysis is enough for text-only skills) and review the
report. A score of `SAFE` with no plausible issues is the default bar; if
it reports `CAUTION`, inspect each finding manually -- most are false
positives for skill content, but treat any that touch executable scripts,
credential handling, or hidden instruction leakage seriously. Re-run the
scanner on the adapted `SKILL.md` after trimming upstream-only files
(templates, plugin metadata, sibling docs) so the result reflects what
will actually live in this repo.

## Adding a new skill

When a real, non-obvious pattern or gotcha comes up more than once,
write it down here rather than re-discovering it next time. Keep each
skill focused on one concern, include the *why* (not just the *what*) so
future edge cases can be judged sensibly, and prefer concrete confirmed
incidents over generic advice.