@linchpinagency/skills 0.1.0

package/README.md

@@ -0,0 +1,337 @@
+# Linchpin Skills
+
+A shared library of **AI agent skills** for the kinds of projects Linchpin builds —
+**WordPress**, **React**, and **Cloudflare Workers**. Skills are agent-agnostic
+instruction sets ([Agent Skills](https://agentskills.io) format) that work in Claude Code,
+GitHub Copilot, and other compatible coding agents.
+
+---
+
+## Getting started
+
+### What a skill actually is
+
+A skill is a markdown file of instructions that your coding agent loads **when your request
+matches its description**. It's how we make an agent behave like a Linchpin developer
+instead of a generic one: it knows we run WordPress Studio, that PHPCS only applies where
+`phpcs.xml.dist` exists, that release-please owns `CHANGELOG.md`, and that every commit
+carries a ClickUp key.
+
+Three things worth knowing up front:
+
+- **You mostly don't invoke skills.** Ask for what you want — "this page is broken on
+  mobile", "get this ready to commit" — and the agent loads the matching skill on its own.
+- **Skills are loaded by the tool, not the model.** Claude, GPT, or anything else running
+  inside Claude Code all read the same `.claude/skills` directory. Switching models changes
+  nothing about which skills exist; switching *tools* does.
+- **They are just files.** Nothing is hosted, nothing phones home. You can read every one of
+  them in `skills/`.
+
+### Install (2 minutes)
+
+Install once, globally, and every project you open gets them:
+
+```bash
+npx -y github:linchpin/skills --global
+```
+
+Verify:
+
+```bash
+npx -y github:linchpin/skills --list
+```
+
+You need GitHub access to this (private) repo, which everyone on the team has. There is no
+npm package yet — see [publishing](#for-maintainers--publishing) for why that's a deliberate
+open question rather than an oversight.
+
+Then start a new session in your project and ask for something real — "what kind of project
+is this?" should pull in `project-context` and get you a summary of the repo shape, local
+environment, and host.
+
+**Re-run the same command to update.** There's no upgrade command; the installer overwrites
+in place and always pulls the current `main`. Do it every few weeks, or when someone
+announces a new skill.
+
+Full flag reference: [Install options](#install-options).
+
+### Your first day
+
+The fastest way to understand the library is to run one loop end to end:
+
+| You want to… | Ask for it naturally | Skill that fires |
+| --- | --- | --- |
+| Understand a repo you just cloned | "what am I working with here?" | `project-context` |
+| Find out why something's broken | "the hero image 404s on mobile" | `investigate` |
+| Test a site like a user, and fix what's found | "QA the checkout flow" | `web-qa` |
+| Check it's ready to commit | "is this ready to commit?" | `quality-gates` |
+| Commit and open the PR properly | "commit this and open a PR" | `commit-and-release` + `task-tracking` |
+| Handle a client support ticket | "Vinfen says their form isn't sending" | `support-triage` |
+| Add guardrails before touching prod | "careful mode — I'm on production" | `safety-hooks` |
+
+The full list is in [Available skills](#available-skills) — 20 of them, each with a
+`When to use` section that says exactly when it applies and which skill to use instead.
+
+**When you want to be explicit**, name the skill: *"use the wp-audit skill on the homepage."*
+Worth doing when a task straddles two skills, or when you want a specific procedure followed.
+
+### Working in Conductor
+
+Conductor runs each workspace in its own **git worktree** — a separate checkout of the repo.
+A project-level install (`./.claude/skills/`) therefore exists only in the workspace where
+you ran it, and disappears the moment you create a new one.
+
+**So for Conductor, install globally** (`--global`). `~/.claude/skills/` is outside the
+worktree, so every workspace picks it up automatically with no per-workspace setup.
+
+Two other things to expect: interactive prompts can behave differently than in a terminal
+session — if a skill seems to be waiting on you, just answer in the chat — and because
+workspaces are independent checkouts, a skill that reports on git state is describing *that*
+workspace only.
+
+### Other tools and models
+
+Claude Code is our primary. If you use something else, install into its directory too:
+
+```bash
+npx -y github:linchpin/skills --global --agent all   # Claude Code, Copilot, Codex, Cursor
+```
+
+Skills are read by the **harness**, so Copilot running a Claude model still needs them in
+Copilot's own folder. Everything here is plain markdown with no Claude-specific syntax, with
+one deliberate exception: `safety-hooks` uses Claude Code hooks to *enforce* confirmation on
+destructive commands, and degrades to documentation elsewhere.
+
+### When a skill is wrong
+
+These encode how we work, so they go stale when how we work changes. If a skill tells the
+agent something outdated, that's a bug worth fixing — open a PR, or an issue if you'd rather
+someone else write it. [`write-a-linchpin-skill`](skills/write-a-linchpin-skill/SKILL.md) is
+the standard, and `npm run validate` checks your work.
+
+---
+
+## Three tiers — and what belongs here
+
+Knowledge about building WordPress lives at three altitudes. This repo owns **only the
+middle one**:
+
+| Tier | Where it lives | What it owns |
+| --- | --- | --- |
+| **Base layer** (upstream) | [`WordPress/agent-skills`](https://github.com/WordPress/agent-skills), vendored + pinned via [`upstream.json`](upstream.json) | Generic "how WordPress works" — block.json, theme.json mechanics, the Interactivity API, performance, WP-CLI ops. |
+| **Linchpin tooling** (**this repo**) | `skills/` | **Portable, cross-project** ways the agency works — operating Studio/Pressable, tying work to ClickUp. Things true on *every* Linchpin project. |
+| **Project layer** (per-repo) | that project's own `AGENTS.md` / `CLAUDE.md` | One project's specific blocks, theme conventions, file paths, and quirks. |
+
+> **Project-specific conventions do NOT go here.** A given site's block/theme conventions
+> (e.g. linchpin.com's color slugs, spacing scale, custom blocks, pattern structure) belong
+> in **that project's repo** — next to the code, in its `AGENTS.md`/`CLAUDE.md` — not in the
+> shared library. The test for "does it belong in this repo?" is: *would it be true on a
+> different client's WordPress project?* If not, it's project layer.
+
+The base layer is pinned to a commit SHA in [`upstream.json`](upstream.json) (upstream has
+no releases yet) and fetched at install time. Bump the `ref` there deliberately and re-test;
+don't float it, or agent behavior changes silently. New **generic** WordPress knowledge
+should be contributed **upstream**, not added here.
+
+## Install options
+
+Skills install via our own zero-dependency CLI, run straight from this repo with `npx`.
+Run it from a project root:
+
+```bash
+# Install every skill into this project's Claude Code skills dir (./.claude/skills)
+npx -y github:linchpin/skills
+
+# Install a specific skill
+npx -y github:linchpin/skills wp-studio-cli
+
+# List what's available
+npx -y github:linchpin/skills --list
+
+# Install for GitHub Copilot instead (-> ./.agents/skills + ./.github/skills)
+npx -y github:linchpin/skills --agent github-copilot
+
+# Install into every agent's directory at once (Claude Code, Copilot, Codex, Cursor)
+npx -y github:linchpin/skills --agent all
+
+# Install to your user-global dir (-> ~/.claude/skills) instead of the project
+npx -y github:linchpin/skills --global
+
+# Install the Linchpin skills only, without the upstream base layer
+npx -y github:linchpin/skills --skip-upstream
+```
+
+> `npx` installs from the repo's default branch, so you always get current `main`. There is
+> no version pinning on this route — pin by publishing to a registry (below) if you ever
+> need it.
+
+> By default the installer also vendors the pinned upstream base layer (see
+> [Three tiers](#three-tiers--and-what-belongs-here)) into the same directory. It needs
+> network access and a system `tar`; if either is missing it warns and still installs the
+> Linchpin skills. Pass `--skip-upstream` to install the Linchpin skills alone.
+
+**Updating:** re-run the same command. The installer overwrites each skill in place, so a
+fresh run always pulls the current `main`.
+
+### Where skills land
+
+| Agent (`--agent`) | Project scope | Global scope (`--global`) |
+| --- | --- | --- |
+| `claude-code` (default) | `./.claude/skills/` | `~/.claude/skills/` |
+| `github-copilot` | `./.agents/skills/` + `./.github/skills/` | `~/.copilot/skills/` |
+| `codex` | `./.codex/skills/` | `~/.codex/skills/` |
+| `cursor` | `./.cursor/skills/` | `~/.cursor/skills/` |
+| `all` | every directory above | every directory above |
+
+A project that wants skills in more than one agent's directory should run
+`--agent all` rather than copying directories around by hand.
+
+> Skills are loaded by the **agent/harness**, not the model — so "Copilot running Claude"
+> still needs the skill installed in Copilot's own directory. The installer handles that.
+
+## Available skills
+
+### Linchpin tooling (this repo)
+
+| Skill | Domain | What it does |
+| --- | --- | --- |
+| `wp-local-setup` | WordPress | Stand up the Linchpin baseline local environment — scaffold a new wp-content-shaped project repo (Composer plugins from wpackagist + packagist.linchpin.com, theme from `base-wp-theme-2026`) and/or wire a repo into a WordPress Studio site by symlinking it in as `wp-content`. |
+| `wp-studio-cli` | WordPress | Operate a local WordPress Studio site — the wordpress-studio MCP first (`wp_cli`, `validate_blocks`, `take_screenshot`), the `studio` CLI as fallback — including the PHP-WASM `ABSPATH` rule. |
+| `wp-audit` | WordPress | Audit a site for performance, accessibility, and visible frontend quality against Core Web Vitals thresholds; prioritized findings with labeled evidence, and before/after re-measurement. |
+| `wp-pressable` | WordPress | Operate a Pressable-hosted site (prod/staging) via the Pressable MCP or SSH+WP-CLI; safely diagnose and fix the "renders locally but not on prod" FSE bug where DB template overrides shadow deployed theme files. |
+| `wordpress-blocks` | WordPress | Author and edit page/post content as valid Gutenberg block markup from a chat interface — pattern-first (reuse the site's synced/registered patterns before composing core blocks), with the grammar rules and the validate-before-insert contract. |
+| `wp-block-conventions` | WordPress | Build custom blocks the Linchpin way — apiVersion 3 under `linchpin/`, dynamic `render.php` + Interactivity API `view.js`, parent/child block context, and the `wp-scripts` build/registration chain shared by `linchpin-blocks` and project functionality plugins. |
+| `wp-implementation-choice` | WordPress | Decide what a request should become — theme work, content, a custom block, a functionality plugin, or an existing plugin — before any code is written. |
+| `design-previews` | Design | Generate three genuinely different visual directions as self-contained HTML previews, screenshot them at desktop and mobile via the Chrome DevTools MCP (or Playwright), and get a pick before theme or block work starts. |
+| `project-context` | Workflow | Orient before acting — repo shape, local environment, host, ClickUp space, and release model, read from the project's own config rather than assumed. Referenced by other skills' Preflight. |
+| `quality-gates` | Workflow | Run a project's own lint, PHPCS, PHPStan, and test gates before committing — detected from `composer.json`, `package.json`, `phpcs.xml.dist`, and `lint-staged`, never assumed. |
+| `web-qa` | Workflow | QA like a real user and fix what you find — front end, wp-admin, and block editor, with severity, evidence, one atomic commit per fix, and a report-only mode. |
+| `investigate` | Workflow | Root-cause a bug before changing anything — reproduce, read the real error, isolate the layer, explain the mechanism, with WordPress first checks. |
+| `browser-automation` | Workflow | The browser ladder, owned once: Chrome DevTools MCP against real Chrome first, Playwright headless as fallback, plus auth handling and WordPress specifics. |
+| `safety-hooks` | Workflow | Enforced guardrails — a `PreToolUse` hook that makes destructive commands (`wp db drop`, `search-replace` without `--dry-run`, force-push, `rm -rf`) require confirmation, plus an optional edit boundary. Claude Code only. |
+| `engagement-types` | Project mgmt | Tell support, site maintenance, projects, product/plugin work, and pre-sales apart — each lives somewhere different in ClickUp and is planned and closed differently. |
+| `support-triage` | Project mgmt | Run a client support request end to end — clarify the real need, reproduce, judge urgency and scope, fix in the right layer, verify, and close the loop with the requester. |
+| `dependency-updates` | Workflow | Handle the dependency work Renovate can't automerge — majors, breaking changes, failing or conflicted bot PRs, security advisories, `@wordpress/*` package sets. |
+| `commit-and-release` | Workflow | Write commits, branches, and PR titles that satisfy the repo's own commitlint rules, and stay out of release-please's way (it owns versions and `CHANGELOG.md`). |
+| `task-tracking` | Workflow | Tie every unit of work to a ClickUp task (or explicit `NO-TASK`) with minimal friction via the ClickUp MCP — resolve/search a task, offer to create one before committing, update it when the work lands, and carry the task key in the conventional-commit scope. |
+| `write-a-linchpin-skill` | Meta | The house standard for authoring skills in this library — placement test, tier model, required frontmatter, the section skeleton, and the four house rules. Enforced by `scripts/validate-skills.mjs`. |
+
+_(More WordPress, React, Cloudflare Workers, marketing, and design skills to come.)_
+
+### Base layer (vendored from upstream, pinned)
+
+Fetched at install time from [`WordPress/agent-skills`](https://github.com/WordPress/agent-skills)
+at the SHA pinned in [`upstream.json`](upstream.json). Curate the set there. Currently:
+`wp-block-development`, `wp-block-themes`, `wp-interactivity-api`, `wp-performance`,
+`wp-wpcli-and-ops`, `wp-plugin-development`, `wp-rest-api`.
+
+## Adding a skill
+
+**The standard lives in [`skills/write-a-linchpin-skill/`](skills/write-a-linchpin-skill/SKILL.md)** —
+load that skill and follow it. It owns the placement test, the tier model (A: `SKILL.md`
+only → B: `+ references/` → C: `+ scripts/`), required frontmatter, the section skeleton,
+and the four house rules. It isn't restated here on purpose: one owner per concern.
+
+The short version:
+
+```
+skills/
+  <name>/
+    SKILL.md            # required — frontmatter: name, description, version
+    references/*.md     # Tier B — detail promoted out of SKILL.md
+    scripts/*.mjs       # Tier C — only when determinism is genuinely needed
+```
+
+- Directory name = frontmatter `name`, and names are **globally unique once installed**.
+  Prefix by domain — `wp-`, `react-`, `cf-`, `seo-`, `design-` — and leave cross-cutting
+  workflow skills (`task-tracking`, `quality-gates`) un-prefixed.
+- Every `SKILL.md` needs `## When to use`, `## Guardrails`, and `## Done`.
+- Add a row to the **Available skills** table above.
+
+Then validate — CI runs the same command on every PR:
+
+```bash
+npm run validate                          # every skill
+node scripts/validate-skills.mjs <name>   # just the one you touched
+```
+
+> **Keep it portable.** Every skill here must be true on *any* Linchpin project of its kind
+> — don't bake in one site's blocks, palette, or file paths. Project-specific conventions
+> belong in that project's own `AGENTS.md`/`CLAUDE.md` (see
+> [Three tiers](#three-tiers--and-what-belongs-here)).
+
+## For maintainers — publishing
+
+**Nothing is published today.** `@linchpinagency/skills` does not exist on npm; the install
+route is `npx -y github:linchpin/skills`, which works for anyone with access to this repo.
+`package.json` is *configured* to publish (`publishConfig.access: "public"`), but running
+`npm publish` is a deliberate decision that hasn't been made — for a good reason:
+
+> **A public package makes this content public.** These skills describe how we run client
+> work: engagement and support workflows, hosting and deploy specifics, and our internal
+> conventions. Before anything is published publicly, someone needs to decide that is
+> acceptable, and the content needs a pass for client-identifying detail (names, ClickUp
+> ids, hostnames) — which belongs in project repos, not here, regardless of publishing.
+
+### How releases work
+
+Releases follow the house convention — **release-please**, same as every other Linchpin repo:
+
+1. Merge conventional commits to `main`. `release-please.yml` keeps a rolling
+   **:gem: Automated Release** PR up to date, with the changelog it would write.
+2. Merge that PR when you want to cut a release. It bumps `package.json`, writes
+   `CHANGELOG.md`, tags `vX.Y.Z`, and publishes a GitHub Release.
+3. That release flips `release_created`, which triggers the `publish` job:
+   `npm run validate`, then `npm publish --provenance --access public`.
+
+**Never hand-edit `package.json`'s version or `CHANGELOG.md`** — release-please owns both
+(see [`commit-and-release`](skills/commit-and-release/SKILL.md)).
+
+### One-time setup before the first release
+
+The automation is wired but has never run. Three things are needed:
+
+1. **Decide the content question above.** Everything else is plumbing; this isn't.
+2. **Create the package with one manual publish.** npm can't attach automation to a package
+   that doesn't exist yet:
+   ```bash
+   npm login                    # must be a member of the @linchpinagency org
+   npm publish --access public  # prepublishOnly runs the validator first
+   ```
+3. **Give CI credentials**, either:
+   - **Trusted Publishing (preferred)** — on npmjs.com, set this repo and
+     `.github/workflows/release-please.yml` as a trusted publisher for the package. No
+     stored secret, and provenance is automatic.
+   - **`NPM_TOKEN` secret** — an npm *automation* token added to this repo's Actions
+     secrets. Simpler to set up, but it's a long-lived credential to rotate.
+
+Until step 3 is done the `publish` job fails rather than skipping, so a release never looks
+published when it isn't.
+
+Options worth weighing first:
+
+- **Stay on the GitHub route** (status quo). Private, zero setup, no registry to maintain.
+  Costs: needs repo access, so external collaborators can't install, and there's no version
+  pinning.
+- **Publish privately** (paid npm org, or GitHub Packages). Keeps content private and adds
+  versioning — but consumers must `npm login` anyway, which removes most of the convenience
+  that made publishing attractive.
+- **Publish publicly** after a content review. Best ergonomics; only appropriate if we're
+  comfortable with the playbook being readable by anyone.
+- **Scope migration.** If the `@linchpin` npm scope is ever acquired, prefer it and deprecate
+  the old name with `npm deprecate @linchpinagency/skills "moved to @linchpin/skills"`.
+
+The package would ship only `bin/`, `skills/`, `upstream.json`, and `README.md` (see `files`
+in `package.json`).
+
+## License & attribution
+
+- **This repo (overlay + installer):** UNLICENSED — internal Linchpin tooling. Update
+  `license` in `package.json` if this is ever released externally.
+- **Base layer:** the upstream skills are **not stored in this repo** — the installer
+  fetches them from [`WordPress/agent-skills`](https://github.com/WordPress/agent-skills) at
+  the pinned SHA, onto the user's machine, at install time. They are
+  **GPL-2.0-or-later**, © WordPress Contributors. Credit to that project for the generic
+  WordPress expertise our overlay builds on. (Upstream is v1 and AI-authored then
+  human-reviewed — treat it as a strong baseline, which is exactly why house rules win on
+  conflict.)

package/bin/install.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// @linchpinagency/skills installer
+// Copies bundled Linchpin skills into a coding agent's skills directory, and (by
+// default) vendors a pinned base layer of upstream WordPress/agent-skills alongside them.
+// Zero runtime dependencies — pure Node (>=18, uses global fetch) + the system `tar`.
+// Re-run to update (it overwrites in place).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+const SKILLS_ROOT = path.join(PKG_ROOT, 'skills');
+const UPSTREAM_MANIFEST = path.join(PKG_ROOT, 'upstream.json');
+
+// Per-agent install locations. `project` paths are relative to cwd, `global` to home.
+// These follow the Agent Skills conventions each tool reads from. An agent may read more
+// than one directory (Copilot honors both `.agents/skills` and `.github/skills`), so every
+// entry is a list.
+const AGENTS = {
+  'claude-code': { label: 'Claude Code', project: ['.claude/skills'], global: ['.claude/skills'] },
+  'github-copilot': { label: 'GitHub Copilot', project: ['.agents/skills', '.github/skills'], global: ['.copilot/skills'] },
+  codex: { label: 'Codex', project: ['.codex/skills'], global: ['.codex/skills'] },
+  cursor: { label: 'Cursor', project: ['.cursor/skills'], global: ['.cursor/skills'] },
+};
+
+function resolveAgents(id) {
+  if (id === 'all') return Object.keys(AGENTS);
+  return AGENTS[id] ? [id] : null;
+}
+
+function parseArgs(argv) {
+  const opts = { agent: 'claude-code', global: false, list: false, help: false, skipUpstream: false, skills: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--global' || a === '-g') opts.global = true;
+    else if (a === '--list' || a === '-l') opts.list = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--skip-upstream') opts.skipUpstream = true;
+    else if (a === '--agent') opts.agent = argv[++i];
+    else if (a.startsWith('--agent=')) opts.agent = a.slice('--agent='.length);
+    else if (a.startsWith('-')) {
+      console.error(`Unknown option: ${a}  (try --help)`);
+      process.exit(1);
+    } else opts.skills.push(a);
+  }
+  return opts;
+}
+
+function readDescription(skillDir) {
+  try {
+    const md = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+    const fm = md.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) return '';
+    const d = fm[1].match(/^description:\s*(.*)$/m);
+    return d ? d[1].replace(/^["']|["']$/g, '').trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+function availableSkills() {
+  if (!fs.existsSync(SKILLS_ROOT)) return [];
+  return fs
+    .readdirSync(SKILLS_ROOT, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(SKILLS_ROOT, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort();
+}
+
+function readUpstreamManifest() {
+  try {
+    const m = JSON.parse(fs.readFileSync(UPSTREAM_MANIFEST, 'utf8'));
+    return Array.isArray(m.sources) ? m.sources : [];
+  } catch {
+    return [];
+  }
+}
+
+// Fetch a repo tarball at a pinned ref, extract it once, and copy the requested skill
+// dirs into every directory in `bases`. Best-effort: any failure (offline, no `tar`,
+// missing skill) warns and returns false rather than aborting the Linchpin install.
+async function installUpstreamSource(source, bases) {
+  const { repo, ref, skills = [] } = source;
+  if (!repo || !ref || !skills.length) return false;
+
+  const url = `https://codeload.github.com/${repo}/tar.gz/${ref}`;
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lp-skills-'));
+  const tarPath = path.join(tmp, 'src.tar.gz');
+  const extractDir = path.join(tmp, 'x');
+  fs.mkdirSync(extractDir);
+
+  try {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    fs.writeFileSync(tarPath, Buffer.from(await res.arrayBuffer()));
+
+    // System tar handles gunzip + long paths + pax headers robustly (bsdtar/gnutar).
+    execFileSync('tar', ['-xzf', tarPath, '-C', extractDir], { stdio: ['ignore', 'ignore', 'pipe'] });
+
+    // GitHub tarballs wrap everything in a single top-level dir (`<repo>-<ref>`); find it
+    // rather than reconstruct its name.
+    const topdir = fs.readdirSync(extractDir).find((n) => fs.statSync(path.join(extractDir, n)).isDirectory());
+    if (!topdir) throw new Error('unexpected tarball layout (no top-level dir)');
+
+    let count = 0;
+    for (const name of skills) {
+      const from = path.join(extractDir, topdir, 'skills', name);
+      if (!fs.existsSync(path.join(from, 'SKILL.md'))) {
+        console.warn(`  ! ${repo}:${name} not found at ${ref} — skipped`);
+        continue;
+      }
+      for (const base of bases) {
+        const dest = path.join(base, name);
+        fs.rmSync(dest, { recursive: true, force: true });
+        fs.cpSync(from, dest, { recursive: true });
+      }
+      console.log(`  ✓ ${name}  (${repo})`);
+      count++;
+    }
+    return count > 0;
+  } catch (err) {
+    console.warn(`  ! Skipped base layer from ${repo}: ${err.message}`);
+    console.warn(`    (Linchpin skills installed fine. Re-run online, or use --skip-upstream to silence.)`);
+    return false;
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function help() {
+  console.log(
+    `
+@linchpinagency/skills — install Linchpin AI agent skills
+
+Linchpin skills are portable, cross-project tooling. By default the installer also vendors
+a pinned base layer of upstream WordPress/agent-skills (generic WordPress expertise)
+alongside them.
+
+Usage:
+  npx @linchpinagency/skills [skills...] [options]
+
+Arguments:
+  skills            One or more Linchpin skill names to install (default: all)
+
+Options:
+  -l, --list        List available skills (Linchpin + pinned base layer) and exit
+  -g, --global      Install to the user-global skills dir instead of the project
+      --agent <id>  Target agent: claude-code (default) | github-copilot | codex | cursor
+                    | all  (installs into every agent's directory)
+      --skip-upstream  Install only Linchpin skills; don't vendor the upstream base layer
+  -h, --help        Show this help
+
+Examples:
+  npx @linchpinagency/skills                    # Linchpin skills + base layer -> ./.claude/skills
+  npx @linchpinagency/skills wp-studio-cli      # one Linchpin skill (+ base layer)
+  npx @linchpinagency/skills --skip-upstream    # Linchpin skills only
+  npx @linchpinagency/skills --agent github-copilot
+  npx @linchpinagency/skills --agent all        # every agent dir in this project
+  npx @linchpinagency/skills --global           # -> ~/.claude/skills
+`.trimStart()
+  );
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) return help();
+
+  const all = availableSkills();
+  const sources = readUpstreamManifest();
+
+  if (opts.list) {
+    console.log('Linchpin skills (portable, cross-project):\n');
+    if (!all.length) console.log('  (none found in this package)');
+    for (const name of all) {
+      const desc = readDescription(path.join(SKILLS_ROOT, name));
+      console.log(`  ${name}${desc ? ` — ${desc}` : ''}`);
+    }
+    for (const s of sources) {
+      console.log(`\nBase layer — ${s.repo} @ ${String(s.ref).slice(0, 12)} (${s.license || 'see repo'}):\n`);
+      for (const name of s.skills || []) console.log(`  ${name}`);
+    }
+    console.log('\nThe base layer is fetched at install time unless --skip-upstream is passed.');
+    return;
+  }
+
+  const agentIds = resolveAgents(opts.agent);
+  if (!agentIds) {
+    console.error(`Unknown agent "${opts.agent}". Known: ${Object.keys(AGENTS).join(', ')}, all`);
+    process.exit(1);
+  }
+
+  // One flat list of destination dirs across every selected agent.
+  const bases = agentIds.flatMap((id) =>
+    (opts.global ? AGENTS[id].global : AGENTS[id].project).map((rel) =>
+      opts.global ? path.join(os.homedir(), rel) : path.join(process.cwd(), rel)
+    )
+  );
+
+  const wanted = opts.skills.length ? opts.skills : all;
+  const unknown = wanted.filter((s) => !all.includes(s));
+  if (unknown.length) {
+    console.error(`Unknown skill(s): ${unknown.join(', ')}`);
+    console.error('Run with --list to see available skills.');
+    process.exit(1);
+  }
+  if (!wanted.length && !sources.length) return console.log('No skills to install.');
+
+  for (const base of bases) {
+    fs.mkdirSync(base, { recursive: true });
+    for (const name of wanted) {
+      const dest = path.join(base, name);
+      fs.rmSync(dest, { recursive: true, force: true });
+      fs.cpSync(path.join(SKILLS_ROOT, name), dest, { recursive: true });
+      console.log(`✓ ${name} -> ${dest}`);
+    }
+  }
+  const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
+  console.log(`\nInstalled ${wanted.length} Linchpin skill(s) for ${labels}.`);
+
+  if (!opts.skipUpstream && sources.length) {
+    console.log('\nVendoring pinned base layer (upstream WordPress/agent-skills):');
+    for (const s of sources) await installUpstreamSource(s, bases);
+    console.log('\nTip: --skip-upstream installs Linchpin skills only.');
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@linchpinagency/skills",
+  "version": "0.1.0",
+  "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
+  "type": "module",
+  "bin": {
+    "skills": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "upstream.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "list": "node bin/install.mjs --list",
+    "validate": "node scripts/validate-skills.mjs",
+    "test": "npm run validate",
+    "prepublishOnly": "npm run validate"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "github-copilot",
+    "agent-skills",
+    "wordpress",
+    "wordpress-studio"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linchpin/skills.git"
+  },
+  "homepage": "https://github.com/linchpin/skills#readme",
+  "bugs": {
+    "url": "https://github.com/linchpin/skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}