skills

Imported from scotthamilton77/agents-config (src/user/.agents/skills/AGENTS.md). Install upstream with npx skills add scotthamilton77/agents-config --skill skills. Copyright stays with the author.

src/user/.agents/skills/ — Shared Skill Sources

Source-of-truth for every skill that gets staged into each active tool's user-space skills directory by scripts/install.sh. Edits here are what land in ~/.claude/skills/, ~/.codex/skills/, ~/.gemini/skills/, and ~/.config/opencode/skills/ on the next install run.

Staging is gated on admission: a SKILL.md without a complete admission: record (prevents or provides, plus cost and remove_when) in its front matter is dropped at deploy and pruned from every tool. Only admitted skills live in this folder; a skill awaiting admission, or retired after it, is not here at all.

An admission record is necessary but not sufficient — a skill can hold a complete record and still fail a mechanical staging check, in which case it deploys nothing. Before telling anyone a skill is available, list the tool's own config directory and confirm it landed.

Layout — flat, depth-1 only

Every immediate subdirectory of this folder is exactly one skill. Skills MUST NOT be nested under organizational subfolders.

skills/
├── <skill-name>/
│   ├── SKILL.md          (required; YAML frontmatter `name:` must match folder name)
│   ├── scripts/          (optional — executable helpers)
│   ├── references/       (optional — context-loaded docs)
│   └── assets/           (optional — templates, fonts, output materials)
└── ...

Why depth-1. All four target runtimes (Claude Code, Codex CLI, Gemini CLI, OpenCode) only discover skills one level deep. Anything nested deeper is invisible to the runtime — verified against each tool's official discovery docs (May 2026). Codex CLI's .system/ exception is OpenAI-owned and not extensible by us.

OSS provenance requirement

Skills derived from, or borrowing substantively from, third-party open-source sources MUST carry an HTML-comment provenance header at the top of SKILL.md, immediately after the YAML frontmatter close:

---
name: my-skill
description: ...
---

<!--
Source: <path to the skill inside the upstream repository>
Upstream: https://github.com/<owner>/<repo> @ <commit-sha>
Last sync: YYYY-MM-DD
Drift policy: <accept-periodic-resync | rewrite-and-divorce | local-fork | track-upstream | selective-amalgamation | ...>
-->

# My Skill
...

Why HTML comments and not a co-located AGENTS.md. Hosts do not read per-skill AGENTS.md files at runtime, and an in-folder note that travels with the SKILL.md is the only durable place for provenance that survives install staging. (See the provenance registry below for the project-wide rollup.)

The pinned commit is the reference copy. This repository does not vendor full upstream trees, because Upstream plus Source already identifies the exact bytes and a clone reproduces them on demand. To inspect drift, clone the upstream repository, check out the pinned SHA, and diff that against the deployed copy. When a skill is resynced to a newer upstream commit, bump the SHA and the Last sync date in its header in the same change.

The pin covers body bytes only, and vendoring is per file. Front matter — description, the admission record, argument-hint — is house-authored on every artifact, pinned or not, so a drift diff showing front-matter divergence is the convention working rather than drift. A vendored file the host skill has no use for is simply not carried, and the header says which files are vendored. Where a vendored body disagrees with its host skill or with the house rules, the host and the house rules win, and the host skill says so in one sentence rather than the body being edited.

That makes each row's accuracy load-bearing: no local copy stands behind it. A pin that names a commit predating the skill it claims to source is not a stale convenience — it is the only record, and it is wrong. Verify a SHA by hashing the file you are pinning and finding the commit whose blob matches, not by picking a commit near the right date.

Absence is recorded here, not on the artifact. A file the host skill declines to carry, and a section cut from a body that is carried, are editorial decisions about this repository: they change no deployed byte, and there is nothing at runtime for them to inform. The provenance header states what the deployed copy is; what it is not belongs in the table below, where someone diffing against upstream will look and a loading agent will not.

Never rename the provenance keys. The installer's sanitizer matches Source: and Upstream: by key name alone, case-insensitively, and never reads their values — so a key rename silently stops provenance being recognised, while a value's shape is free. A skill that amalgamates — lifts specific patterns rather than resyncing byte-for-byte — keeps the same keys and encodes the amalgam semantics in the Drift policy: value (selective-amalgamation), never in a renamed key like Amalgamation source:. If a new policy value is needed, add it to the enum above rather than inventing an ad-hoc key.

Skill provenance registry

One row per OSS-derived or OSS-influenced artifact on the deployed surface — skills, and any command or rule that came from the same sources, since the admission gate sends all of them to this one table. Artifacts built from scratch in-repo do not appear. When one is retired, delete its row — the file carries its own provenance header with it wherever it goes, and git holds the rest.

The table tracks src/, not the branch it is sitting on. A wave of admissions arriving as several PRs consolidates its rows here first, so that one file is not the conflict every later merge has to resolve by hand. A row may therefore name an artifact that has not landed on this branch yet. The obligation runs the other way and is unaffected: a retired artifact's row goes, and a row for something that will never land is a defect, not a forward reference.

Update this table whenever an artifact is added, replaced, retired, or amalgamated from an OSS source.

Upstream and Path in upstream together fetch the exact reference bytes. Last sync is a different fact — when the deployed copy was last reconciled against upstream — so it can legitimately predate the pinned commit, as handoff's does. zoom-out is the opposite case: its path is gone from upstream's head, so the pin is the last commit that still holds the reference bytes and no later pin exists to move to.

Claude-only front matter is not a reason to leave the shared tree. The installer projects capability keys per target tool at deploy: disable-model-invocation, allowed-tools and argument-hint are kept for Claude and dropped for Codex, Gemini and OpenCode. For disable-model-invocation on Codex the drop comes with a translation — the installer generates Codex's own declaration, an agents/openai.yaml sidecar carrying policy.allow_implicit_invocation: false, beside the deployed SKILL.md — while Gemini and OpenCode have no equivalent to translate onto.

Placement still turns on capability-dependency, but of the skill's procedure rather than its front matter. A skill whose steps require a Claude-only mechanism belongs in the Claude tree. So does one whose admission record depends on behaviour the other tools cannot reproduce — dropping a key removes the bytes, not the gap, so a skill that must not fire unprompted is still model-invocable on OpenCode.

Extracted helpers must be wired in

Extracting a helper script out of in-model skill code does not change the live path: SKILL.md keeps running the in-model code until it is rewired to invoke the helper, so the helper chain can carry a latent, unexercised contract bug while every gate reports green. Treat "helper added but not yet invoked by SKILL.md" as a review smell, and drive the documented helper chain end-to-end on a fixture before merging — a review that reads one file at a time cannot see the gap.

Companion folders

• src/user/.claude/skills/ — skills that depend on Claude-only capabilities (depth-1 same rule). Placement is by capability-dependency: a skill that works on every supported tool belongs in this folder; one that needs a Claude-specific capability belongs in that one.