gregoryfoster/skills

A shared library of Agent Skills for use across projects.

Skills are folders of instructions, scripts, and references that agents can discover and use to perform better at specific tasks.

Skills

Skill	Triggers	Description
reviewing-code	CR, code review, perform a review	Structured code & documentation review with severity-tiered findings. Terse per-item directives, or a blanket address the findings[, emphasizing X] that pre-authorizes the whole round. Fallback of last resort for any stack with no dedicated variant
reviewing-code-php	CR, code review, perform a review	PHP/WordPress/Bedrock/Sage 11 variant of reviewing-code
reviewing-code-python-fastapi	CR, code review, perform a review	Python/FastAPI variant of reviewing-code (async route handlers, Alembic migration safety, OpenAPI contract drift)
reviewing-code-python-click	CR, code review, perform a review	Python/Click CLI variant of reviewing-code (Click decorator order, custom ParamTypes, command registration)
reviewing-architecture	AR, architecture review, architectural review	High-level architectural review across 14 structural dimensions
enforcing-architecture	add a fitness function, enforce this contract, lock this rule	Graduate an accepted architecture finding into an executable fitness function (import-linter / dependency-cruiser / deptrac / module-size gate / OpenAPI drift guard), add the dev dependency, document it in AGENTS.md, and wire it into the detected check surface as a reviewable diff
auditing-ci-cost	audit CI, CI cost, Actions spend, optimize CI	Audit GitHub Actions spend by measuring the cost shape first: a per-job billed-minute census computed from job timestamps, platform-incident days separated from the structural baseline, then a prescription that branches on job COUNT vs job DURATION — the levers for one are actively wrong for the other. Ships a path-filter replay gated on zero false skips, a required non-levers section, and a handoff to enforcing-architecture
shipping-work	ship it, push GH, close GH, wrap up	Commit, push, comment, and close GitHub issues. Fallback of last resort for any stack with no dedicated variant
shipping-work-php	ship it, push GH, close GH, wrap up	PHP/WordPress/Bedrock/Sage 11 variant of shipping-work
shipping-work-python-fastapi	ship it, push GH, close GH, wrap up	Python/FastAPI variant of shipping-work (Alembic migrations, systemd service restarts)
shipping-work-python-click	ship it, push GH, close GH, wrap up	Python/Click CLI variant of shipping-work (Click command registration, --help output)
managing-skills	add skill repo, add external skills, manage skills, update vendor skills, install skills hook, enable auto-refresh	Add, update, and remove external skill repos using git submodules + symlinks; optionally install a once-per-day auto-refresh hook
init-project-fastapi	init project, bootstrap project, new fastapi project, set up foundation	Bootstrap a new FastAPI service with SSH deploy key, pyproject.toml, structured logging, TDD scaffold, vendor skill submodules, and GitHub issue tracking
vendoring-openapi-client	vendor openapi client, vendor api client, generate api client from openapi, refresh vendored client, client drift guard	Vendor a generated Python client for a producer service's OpenAPI: committed spec snapshot + provenance sidecar, optional surface filtering, pinned openapi-python-client generation, lint/coverage/diff carve-outs, and tiered drift guards (hermetic CI regen-diff; scheduled or on-VM live-drift)
init-socraticode	init socraticode, set up code search, index this project, socraticode setup	Install, configure, and index SocratiCode semantic code search: host preflight (Docker, or a shared Qdrant store; Node/npx), plugin enablement, a project-adapted Code Exploration Policy + prefetch hook, a context-artifacts manifest, and a blocking index verified green (embeddings + graph + artifacts)
orchestrating-issue-backlog	orchestrate backlog, prioritize issues, plan issue execution, clear backlog	Prioritize an open issue backlog, analyze conflict zones, design a parallel-safe batch execution plan using git worktrees, and hand off to an agent team
using-git-worktrees	create worktree, new worktree, destroy worktree, merge worktree, wt	Workflow for parallel branch checkouts via git worktree: standardizes creation, lifecycle, port/env separation, and cleanup
patching-hosts	patch the host, OS updates, security updates, apply updates, unattended-upgrades, needrestart, is this host patched	Patch a Linux host's OS packages safely: read the actual update state against the posture its knob declares, measure the pending set by class, then a gated apply in held steps with a recovery point, needrestart in list mode, a detached in-guest reboot chain, and post-boot verification. In development (#313)
using-mayfly-chat	mayfly, open a channel, join the channel, chat with , agent chat	Live agent-to-agent exchange over a Mayfly Chat channel (end-to-end encrypted, ephemeral, the URL is the only credential): decide per question whether a channel is warranted, keep the URL out of argv and every durable store, post from files with compare-and-swap cursor discipline, listen in the background, verify every peer claim, and land outcomes on issues before goodbye
writing-plans	write a plan, plan this, let's plan	Discipline for writing a short, reviewed plan before non-trivial implementation; plans land in a configurable plans directory (default docs/plans/) with a prescribed structure
curating-context	curate context, context budget, hone AGENTS.md, trim AGENTS.md, prune context	Keep AGENTS.md and its live reference docs small, true, and navigable: token-budget census, mechanical fact verification, keep/demote/tighten/delete classification, relocate-not-delete edits, and a committed JSONL telemetry ledger with a cross-cohort roll-up. Ships three surfaces — a weekly scheduled measurement that keeps the series accumulating, an installable PostToolUse write guard, and a review-time delta the reviewing-code* variants call automatically

Structure

skills/
  <skill-name>/
    SKILL.md          # Required: frontmatter + instructions
    scripts/          # Executable scripts
    references/       # Supplementary docs (loaded on demand)

Usage

Point your agent at this repo's skills/ directory. For Claude Code and similar tools, add a <available_skills> block to your system prompt or AGENTS.md using the skills-ref CLI:

skills-ref to-prompt skills/reviewing-code skills/reviewing-architecture skills/shipping-work

Consuming this repo

The recommended pattern for using these skills in your project is git submodule + symlinks:

# 1. Add as a submodule
git submodule add https://github.com/gregoryfoster/skills.git skills-vendor/gregoryfoster-skills

# 2. Symlink the skills you want — the whole directory, so everything under it
#    tracks upstream by construction. Vendoring file by file also works and is
#    in cohort use, but then any file committed as a REGULAR file silently
#    stops receiving updates: https://github.com/gregoryfoster/skills/issues/256
#    (relative paths assume skills-vendor/ is at the repo root)
mkdir -p skills
ln -s ../../skills-vendor/gregoryfoster-skills/skills/reviewing-code skills/reviewing-code
ln -s ../../skills-vendor/gregoryfoster-skills/skills/shipping-work skills/shipping-work

# 3. Install the doctor preflight (self-heals dangling symlinks in fresh
#    worktrees, shallow CI clones, etc., and reports a vendored file that
#    stopped tracking upstream)
bash skills-vendor/gregoryfoster-skills/skills/managing-skills/scripts/install-doctor.sh

# 4. Install the auto-refresh hook — OPTIONAL, but skipping it means the
#    submodule pointer only ever moves when somebody bumps it by hand.
#    Four of twelve audited consumers skipped it and sat on one commit for
#    over a week: https://github.com/gregoryfoster/skills/issues/167
bash skills-vendor/gregoryfoster-skills/skills/managing-skills/scripts/install-refresh.sh

# 5. Commit
git add .gitmodules skills-vendor/gregoryfoster-skills skills/ .skills/doctor.sh \
        .claude/hooks/skills-submodule-update.sh .claude/settings.json
git commit -m "feat: add gregoryfoster/skills submodule"

The hook needs both the symlink and the .claude/settings.json entry — Claude Code runs what settings.json names, so a symlink alone looks installed and refreshes nothing. install-refresh.sh --check reports both (exit 0 present, 3 missing — or installed as a copy where a symlink is possible).

Symlinked skills are auto-discovered by the agent framework. To override a global skill with project-specific behavior, replace the symlink with a committed directory of the same name.

See managing-skills for the full procedure.

Project-level overrides

Projects can supersede any skill by placing a directory with the same name under their local /skills/ folder. The local version is a complete replacement — see AGENTS.md for details.

Spec

Follows the Agent Skills specification. Validated with skills-ref.

License

MIT