global-skills/README.md

# global-skills

Reusable workflows for coding agents: planning, debugging, API and database design,
security, UI, writing, performance benchmarking, and optional spec-driven development.
Skills help an agent complete the requested work with clear steps and appropriate verification.

This repository is the canonical source for 20 shared skills on this host.
Installed skills link back to the source, so edits take effect without copying
files into each agent's directory. The workflows favor direct execution: use
existing context, preserve user work, and check only what the change needs.

## Install

Requires Bash, Python 3, and a filesystem supporting symbolic links. The supplied
installer targets Linux-style home directories and uses Python's standard library.

From a checkout:

```sh
cd /path/to/global-skills
./sync-skills.sh --dry-run
./sync-skills.sh
./sync-skills.sh --check
```

The default targets are:

| Target | Skill directory |
| --- | --- |
| OpenCode / shared agents | `~/.agents/skills` |
| Codex | `~/.codex/skills` |
| Claude Code | `~/.claude/skills` |

Sync also includes JEV skills when `~/Projects/work/JEV/.agents/skills` exists.
It preserves unrelated files and symlinks, removes stale managed links, and rejects
source-name collisions. Antigravity uses separate source-path configuration.

See [installation and usage](docs/installation.md) for first-time setup, installing
one skill, custom targets, Antigravity configuration, updates, and troubleshooting.

## Use

Ask for the outcome in normal language. An agent can select a skill from its
name and description, or you can explicitly name the workflow:

- “Use debugging-workflow to diagnose this failing request.”
- “Use interface-kit to improve this form using the existing components.”
- “Use junior-to-senior to review this implementation plan.”
- “Use benchmark-refactor to profile this module and evaluate optimizations.”
- “Use spec to write a specification, then implement task T1 with build.”

The spec suite applies when you choose that workflow. Ordinary bug fixes and
feature edits do not require a spec. Requests to review or report remain read-only.
Discovery and activation depend on the agent; this repository installs Markdown
instructions and links, without adding runtime hooks or model calls.

For projects with substantial architecture or design history, keep a concise,
project-owned context index pointing to the key code paths and design documents.
Load it when the task needs that history; avoid generating directory-by-directory
documentation unless maintainers will keep it accurate.

## Catalog

| Work | Skills |
| --- | --- |
| Plan and review | [grill](skills/grill/SKILL.md), [junior-to-senior](skills/junior-to-senior/SKILL.md), [review](skills/review/SKILL.md) |
| Adopted spec workflow | [spec](skills/spec/SKILL.md), [build](skills/build/SKILL.md), [check](skills/check/SKILL.md), [backprop](skills/backprop/SKILL.md), [caveman](skills/caveman/SKILL.md) |
| Fix and simplify | [debugging-workflow](skills/debugging-workflow/SKILL.md), [deepen](skills/deepen/SKILL.md), [emergency-procedures](skills/emergency-procedures/SKILL.md) |
| Architecture | [api-design](skills/api-design/SKILL.md), [database-design](skills/database-design/SKILL.md), [app-security](skills/app-security/SKILL.md), [benchmark-refactor](skills/benchmark-refactor/SKILL.md) |
| UI and writing | [interface-kit](skills/interface-kit/SKILL.md), [fuck-slop](skills/fuck-slop/SKILL.md) |
| Maintenance | [git-workflow](skills/git-workflow/SKILL.md), [deliver-file](skills/deliver-file/SKILL.md), [skill-architect](skills/skill-architect/SKILL.md) |

JEV supplies `context-architect`, `lint-architect`, `typesafe-ai`, `doc-architect`,
and `system-one-balance-protocol`. Its `anti-slop-editor` is a compatibility alias
to `fuck-slop`.

## Maintain

Content edits propagate through existing links immediately. Sync after adding,
removing, or moving a skill. Running agents may need a new session to refresh their
cached skill list or instructions.

```sh
python3 bin/validate-skills   # metadata, local links, duplicate names; read-only
./sync-skills.sh --check      # installed-link drift/conflicts; read-only
```

Validation is for catalog maintenance, not a preflight for everyday coding.
See [authoring and maintenance](docs/maintenance.md) for metadata, ownership,
verification conventions, and tool regression checks.

## Workflow conventions

[Shared workflow and verification](protocols/workflow.md) defines proportional
checks and preservation of user work. User and repository instructions take
precedence. Telemetry and pull requests follow [the telemetry protocol](protocols/telemetry.md).
Repository governance rules and boundary tiers adhere to [the agents template](protocols/agents-template.md).
References load on demand; there is no required phase anatomy, per-task commit,
separate review invocation, or blanket full-suite run.

Skills declare `scope: global`, `project`, or `alias`. Scope documents applicability;
it does not change a harness router by itself. JEV-dependent skills state their
project requirements. Some optional references assume a sibling JEV checkout.

## Host-specific file delivery

[deliver-file](skills/deliver-file/SKILL.md) uses `bin/t3-deliver` to print a command
for the user's Windows machine to pull files over Tailscale SSH. Its host address
is configured for this machine; adapt it before using delivery on another host.
The helper assumes `realpath` locally and OpenSSH scp with SFTP support remotely.
It prints a command and does not start a transfer.