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).

## 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 MIT licenses, 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)

## 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.