@maccesar/aiskills 1.18.1 → 1.20.0

package/README.md

@@ -74,6 +74,7 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 | stitch-showcase      | Design Tools | Google Stitch export workflow        | 16 files        |
 | session-log          | Project      | Convention + 3 A/B rounds            | 2 files         |
 | seo-launch           | Web / SEO    | Head tags, share cards, server files | 5 files         |
+| npm-supply-chain     | npm / CI     | npm and GitHub changelogs, 2025–2026 | 5 files         |
 
 Use `aiskills list` to see available skills from the command line. Pull requests are welcome.
 
@@ -104,7 +105,7 @@ Example prompts:
 ```
 
 How it works:
-1. **Detect** — reads git status, last tag, existing commits since the tag, version file, `CHANGELOG.md`, `README.md`, and `gh` availability.
+1. **Detect** — reads git status, last tag, existing commits since the tag, version file, `CHANGELOG.md`, `README.md`, `gh` availability, and `.github/workflows/` to see what a pushed tag will set off. Secondary version files count: a repo carrying `.claude-plugin/plugin.json` gets it bumped to the same number in the same commit, because Claude Code compares that field to invalidate its plugin cache and marketplace users otherwise keep running the old code.
 2. **Group the working tree** — reads each modified/untracked file's diff, infers intent, and groups files into N proposed semantic commits (`feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `build`, `ci`). Excludes screenshots in repo root, scratch files, suspicious binaries — and lists them so you can override.
 3. **Infer bump** — across the union of (existing commits since tag) + (proposed semantic commits): `BREAKING CHANGE` / `!:` → major, any `feat:` → minor, otherwise patch. An argument overrides.
 4. **Compose CHANGELOG** — promotes `[Unreleased]` if present, or generates a Keep-a-Changelog entry from the union of all commits being shipped.
@@ -493,14 +494,57 @@ How to invoke it — in whatever words you'd use anyway:
 
 ---
 
+### npm-supply-chain
+
+Both directions of the registry, after everything about them changed between November 2025 and July 2026: how a package gets published, and what happens on the machine installing one.
+
+On the publishing side, the long-lived credential is gone. Classic tokens were removed in November 2025 and revoked in December; `npm login` now opens a **two-hour session** rather than writing a token, which is why publishing by hand asks for credentials every time. The remaining token type caps at 90 days for write access, lost account and package management on 31 July 2026, and loses direct publish around January 2027. The one path without an expiry is **trusted publishing**: GitHub Actions identifies itself to npm with a short-lived OIDC credential, so there is no secret to store and npm attaches provenance to the publish automatically.
+
+On the installing side, **npm v12** turns off three things that used to happen on their own: dependency lifecycle scripts and implicit node-gyp builds, git dependencies, and remote tarballs. The skill covers what breaks, how `npm approve-scripts` works, and why the resulting allowlist gets committed.
+
+`scripts/auditar_npm.py` measures the repo instead of asking about it — standard-library Python, nothing to install, writes nothing:
+
+```bash
+python3 <SKILL_DIR>/scripts/auditar_npm.py            # the repo in the current directory
+python3 <SKILL_DIR>/scripts/auditar_npm.py ~/code/foo
+python3 <SKILL_DIR>/scripts/auditar_npm.py --no-network
+```
+
+It reports tokens sitting in `~/.npmrc` or the project `.npmrc`, Actions secrets that look like npm credentials **and whether any workflow still references them** (one that does not is an orphaned live credential), how each publishing workflow authenticates, `package.json` and `.claude-plugin/plugin.json` versions that have drifted apart, shields.io badges pointing at a package name that does not exist, dependencies that would prompt for approval on npm v12, and the local npm version. Secret *names* are all it reads; a value is never printed.
+
+The badge check earns its place from this repo's own history: three badges asked for `aiskills` while the package publishes as `@maccesar/aiskills`, so shields.io rendered "package not found" instead of an error and the downloads badge hid a real 568/month for months.
+
+| Reference file | Covers |
+| --- | --- |
+| `authentication.md` | the timeline, session-based login, the three token types, the 2FA-bypass phases with dates, the npmjs.com banner, and which paths remain |
+| `trusted-publishing.md` | the publisher form field by field, `id-token: write`, the Node/npm minimums, provenance, the version guard, and the mistakes that break a registration |
+| `install-defaults.md` | npm v12 defaults, `npm approve-scripts`, the committed allowlist, which packages break, and the `ignore-scripts` trap |
+| `migration.md` | the once-per-project procedure in order, what only the package owner can do, and the cleanup the old flow leaves behind |
+| `verification.md` | the command behind each claim — including why `npm view` reports a stale version and what npmjs.com shows when OIDC worked |
+
+`assets/publish.yml` is the workflow template, commented line by line.
+
+How to invoke it — in whatever words you'd use anyway:
+
+```
+"¿por qué me pide login cada vez que publico?"
+"I want to publish from GitHub Actions instead of my laptop"
+"¿qué es esto del bypass 2FA que me sale en npmjs?"
+"npm install stopped running postinstall after I upgraded"
+"cómo quito el NPM_TOKEN de este repo"
+```
+
+---
+
 ## CLI reference
 
 ### aiskills list
 
-Lists all available skills with their descriptions.
+Lists all available skills with their descriptions, marking each one installed (✓) or not (✗). It works before you have installed anything — descriptions for a skill that is not installed come from the copy bundled in this package — so the list doubles as the catalog of what is on offer.
 
 ```bash
 aiskills list
+aiskills ls    # same thing
 ```
 
 ---
@@ -688,19 +732,21 @@ Skills are plain Markdown files. To add a new one:
 
 ### Skill frontmatter format
 
+Only the six fields the [agentskills.io specification](https://agentskills.io/specification) defines: `name` and `description` are required; `license`, `compatibility`, `metadata` and `allowed-tools` are optional. Anything else is ignored by some agents and rejected by others.
+
 ```yaml
 ---
 name: skill-name
-description: >
-  One paragraph describing what this skill does and when to use it.
-when_to_use: >
-  - Bullet list of trigger conditions
-source: "Book title, documentation name, or other authoritative source"
-anti_hallucination_note: >
-  What the AI should NOT do (invent, supplement, guess).
+description: 'What this skill does, the words a user would actually say when they need it, and — after "Not for:" — the neighbouring tasks it should not answer.'
+allowed-tools: Read, Grep, Glob, Bash        # only if the skill needs more than reading
+compatibility: Requires Python 3             # only if it has real environment requirements
 ---
 ```
 
+The `description` is the only part an assistant reads when deciding whether to load the skill, so every trigger belongs in it. A `## When to use` section in the body cannot affect that decision — it loads after the decision was made — and costs context on every invocation.
+
+**The `description` must stay under 1024 characters** and the `name` under 64, both enforced by `test/manifest.test.js`. Past those limits some agents fail to load the skill at all. The block as a whole has no limit, so an optional field costs nothing against the description's budget.
+
 ### Guidelines
 - Every skill must cite a specific source (book, official docs, specification)
 - No invented numbers, rules, or advice not found in the source

package/bin/aiskills.js

@@ -25,6 +25,7 @@ program
 // List command
 program
   .command('list')
+  .alias('ls')
   .description('List available AI skills')
   .action(listCommand);
 

package/commands/release.md

@@ -77,6 +77,9 @@ Do all of this **internally**. Do not print a status summary or any "Step 1" hea
    - `*.podspec` → CocoaPods (edit `s.version`)
    - None → **versionless** mode (commit + push + optional tag).
 
+   **Then check for secondary version files.** They accompany the primary one, they do not replace it, and they must reach the **same** number in the **same** commit:
+   - `.claude-plugin/plugin.json` → a Claude Code plugin manifest. Claude Code compares this `"version"` field to decide whether to invalidate its cached copy of the plugin, so a repo that ships both to npm and to a plugin marketplace can publish new code while marketplace users keep running the old one indefinitely. This is not hypothetical: a project shipped 2.6.0 to npm with `plugin.json` still reading 3.0.0, and the marketplace announced a version that did not exist. If the repo also has a CI job that compares the tag against its version files, an unbumped `plugin.json` fails the release outright.
+
 2. **Detect CHANGELOG strategy:** if `CHANGELOG.md` exists and has `## [Unreleased]` → **promote mode**; if exists without it → **generate mode**; if missing → **skip CHANGELOG entirely** (do not create one without asking).
 
 3. **Detect README version references:** grep `README.md` for the current version string and `v\d+\.\d+` badge patterns. Note locations that need updating, or note that none exist.
@@ -143,7 +146,12 @@ Do all of this **internally**. Do not print a status summary or any "Step 1" hea
 
    In `private` mode these flags are **not** raised — tag and GitHub release are skipped by default anyway, so there is nothing to confirm.
 
-9. **Note genuine anomalies** for Step 4: no remote, no `gh`, README/CHANGELOG languages disagree, an excluded file is borderline. **Do not** flag a dirty working tree itself — that's expected. **Do not** flag "branch is not main" as an anomaly either — handle it via the dedicated merge prompt below. **Do not** flag "no prior tags" or "no prior releases" as an anomaly on a private repo — in private mode we're not creating either anyway, so it's not a question. On public mode the `first-tag` / `first-release` flags from Step 1.8 are surfaced as their own ⚠️ lines (see Step 4 Part C), not in the generic anomalies list.
+9. **Detect what the pushed tag will trigger.** Read `.github/workflows/*.yml` (if the directory exists) and look for a workflow whose `on:` block includes `push:` with `tags:` matching `v*` **and** whose steps publish (`npm publish`, `gh release`, `cargo publish`, `twine upload`, or similar).
+
+   - **A publishing workflow exists** → Phase 3's `git push origin vX.Y.Z` is not just a label, it **starts a publication**. Hold the workflow's filename for Step 4 and Phase 5; the user is entitled to know that confirming ships the package, not just tags it.
+   - **The project is npm (a `package.json` with a `name` and no `"private": true`) and no such workflow exists** → hold a one-line recommendation for Step 4. Publishing then still requires an interactive `npm login`, which since December 2025 opens a two-hour session rather than writing a durable token. If the `npm-supply-chain` skill is available in this session, name it as the way to set trusted publishing up. **Do not invoke it and do not create the workflow here** — that is a once-per-project migration that also needs the package owner's 2FA on npmjs.com, and it has no business happening in the middle of a release the user is about to confirm.
+
+10. **Note genuine anomalies** for Step 4: no remote, no `gh`, README/CHANGELOG languages disagree, an excluded file is borderline. **Do not** flag a dirty working tree itself — that's expected. **Do not** flag "branch is not main" as an anomaly either — handle it via the dedicated merge prompt below. **Do not** flag "no prior tags" or "no prior releases" as an anomaly on a private repo — in private mode we're not creating either anyway, so it's not a question. On public mode the `first-tag` / `first-release` flags from Step 1.8 are surfaced as their own ⚠️ lines (see Step 4 Part C), not in the generic anomalies list.
 
 ---
 
@@ -277,8 +285,10 @@ CHANGELOG entry:
 - ...
 
 README updates (gaps found): <one-line per gap, e.g. "add /release row to Available commands table + new section">  ← omit this line if no gaps
-Release commit: bumps <version-file> A.B.C→X.Y.Z, inserts CHANGELOG section, applies README updates. Subject: `<exact line>`.
+Release commit: bumps <version-file> A.B.C→X.Y.Z (+ <secondary version file> to the same number), inserts CHANGELOG section, applies README updates. Subject: `<exact line>`.
 Push: release commit to <branch>.
+Publishing: pushing the tag triggers `<workflow>.yml`, which publishes to <registry>.   ← include ONLY when Step 1.9 found a tag-triggered publishing workflow; localize to user's language
+Sin publicación automática: este repo publica a mano (`npm login` abre una sesión de dos horas). El skill `npm-supply-chain` monta trusted publishing si te interesa — no lo toco aquí.   ← include ONLY when Step 1.9 found an npm project with no publishing workflow; localize to user's language
 <one of the three rendering modes below — pick by visibility>
    • Public / internal repo: `Tag + GitHub release: vX.Y.Z to <branch> + release with CHANGELOG notes.`
    • Private repo (default): `Repo privado → omitiendo tag y GitHub release. (responde "con tag" si quieres crear el tag de todos modos)` — localize to user's language.
@@ -331,7 +341,7 @@ After Phase 1, the working tree should be clean except for files explicitly list
 
 **Phase 2 — Release commit.**
 
-1. **Bump the version file:**
+1. **Bump the version file** (and every secondary version file found in Step 1.1, to the identical number — `.claude-plugin/plugin.json` with `Edit`):
    - npm: `npm version <patch|minor|major> --no-git-tag-version`
    - tiapp.xml: `Edit` only the **top-level** `<version>` element. Verify no `<module version=...>` matches in your edit.
    - composer.json: `Edit` `"version"` if present; skip if absent.
@@ -345,7 +355,7 @@ After Phase 1, the working tree should be clean except for files explicitly list
    - The documentation gap patches (new command rows, new sections, updated tables) so the README reflects the user-visible surface being shipped in this release.
    - Plus any version badge / install snippet that referenced the old version. Apply with `Edit` per location. Skip only if Step 1.6 found nothing.
 
-4. **Stage exactly the release-commit files** (the bumped version file + lockfile if `npm version` updated it + `CHANGELOG.md` + `README.md` if changed). Use explicit `git add <paths>`, not `git add -A`.
+4. **Stage exactly the release-commit files** (the bumped version file + any secondary version file + lockfile if `npm version` updated it + `CHANGELOG.md` + `README.md` if changed). Use explicit `git add <paths>`, not `git add -A`.
 
 5. **Commit:** `git commit -m "chore(release): vX.Y.Z"` (or the project's release-commit convention).
 
@@ -381,7 +391,15 @@ If `mode=none` (default), skip this phase entirely.
 
 If a Phase 4 step fails, the release itself is already shipped (Phases 1–3 succeeded). Surface the merge/PR failure as a non-fatal note in the final report — do not unwind the release.
 
-**Phase 5 — Final report (one line plus URL).**
+**Phase 5 — Wait for the publish, then report (one line plus URL).**
+
+If Step 1.9 found a tag-triggered publishing workflow and the tag was pushed, the release is not finished when `git push` returns — the workflow is what publishes, and it can still fail on a version guard, on tests, or on a registry credential that was never configured. Wait for it before reporting:
+
+```bash
+gh run watch --exit-status   # or: gh run list --workflow=<workflow>.yml --limit 1
+```
+
+Report its outcome in the final line. If it failed, say so plainly with the reason and the run URL — the commits and the tag are already landed, so this is information, not something to unwind. Skip this entirely when no such workflow exists or `gh` is unavailable.
 
 ```
 ✓ vX.Y.Z → <release URL>
@@ -389,6 +407,8 @@ If a Phase 4 step fails, the release itself is already shipped (Phases 1–3 suc
 ```
 
 The "optional note" only appears if something was non-routine — examples:
+- `published by <workflow>.yml` (when the tag triggered a publish and the run went green)
+- `<workflow>.yml failed: <reason> — <run URL>` (the tag and commits are landed; the publish is not)
 - `merged to main; now on <main-branch>` (when Phase 4 ran successfully with mode=merge; include the new main HEAD short hash)
 - `PR opened: <pr-url>` (when Phase 4 ran with mode=pr)
 - `merge to main aborted: main has diverged — resolve manually`

package/lib/commands/list.js

@@ -111,25 +111,44 @@ export function parseDescription(frontmatter) {
 }
 
 /**
- * Read a skill's description from disk.
- * @param {string} skillDir - Directory holding the skill's SKILL.md
- * @returns {{description: string|null, installed: boolean}}
+ * Read a description out of one SKILL.md.
+ * @param {string} skillMd - Path to a SKILL.md
+ * @returns {string|null} The first sentence, or null when unreadable
  */
-function readSkillMetadata(skillDir) {
-  const skillMd = join(skillDir, 'SKILL.md');
-  if (!existsSync(skillMd)) {
-    return { description: null, installed: false };
-  }
-
+function readDescription(skillMd) {
   try {
     const content = readFileSync(skillMd, 'utf8');
     const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!frontmatter) return { description: null, installed: true };
-
-    return { description: parseDescription(frontmatter[1]), installed: true };
+    if (!frontmatter) return null;
+    return parseDescription(frontmatter[1]);
   } catch {
-    return { description: null, installed: true };
+    return null;
+  }
+}
+
+/**
+ * Read a skill's description, preferring the installed copy and falling back
+ * to the one bundled in this package.
+ *
+ * The fallback is what lets the list describe a skill that is not installed
+ * yet — which is exactly when someone runs `aiskills list` and needs to know
+ * what they would be installing. `skills/` ships in the npm tarball, so the
+ * bundled copy is there for every install channel.
+ * @param {string} skillDir - Where the skill would be installed
+ * @param {string} name - Skill name, used to find the bundled copy
+ * @returns {{description: string|null, installed: boolean}}
+ */
+function readSkillMetadata(skillDir, name) {
+  const installedMd = join(skillDir, 'SKILL.md');
+  if (existsSync(installedMd)) {
+    return { description: readDescription(installedMd), installed: true };
   }
+
+  const bundledMd = new URL(`../../skills/${name}/SKILL.md`, import.meta.url);
+  return {
+    description: existsSync(bundledMd) ? readDescription(bundledMd) : null,
+    installed: false,
+  };
 }
 
 export async function listCommand() {
@@ -139,21 +158,13 @@ export async function listCommand() {
 
   const skillsDir = getAgentsSkillsDir();
 
-  if (!existsSync(skillsDir)) {
-    console.log(chalk.yellow('No skills installed yet.'));
-    console.log('Install with:');
-    console.log(chalk.cyan('  aiskills install'));
-    console.log('');
-    return;
-  }
-
   const rows = [];
   let installedCount = 0;
   let maxNameLen = 0;
 
   for (const name of SKILLS) {
     const skillDir = join(skillsDir, name);
-    const { description, installed } = readSkillMetadata(skillDir);
+    const { description, installed } = readSkillMetadata(skillDir, name);
 
     if (installed) installedCount++;
     if (name.length > maxNameLen) maxNameLen = name.length;
@@ -179,6 +190,18 @@ export async function listCommand() {
   }
 
   console.log('');
+
+  if (installedCount === 0) {
+    // Naming the directory would point at somewhere that does not exist yet.
+    console.log(chalk.gray(`0/${SKILLS.length} installed`));
+    console.log('');
+    console.log(chalk.yellow('No skills installed yet.'));
+    console.log('Install with:');
+    console.log(chalk.cyan('  aiskills install'));
+    console.log('');
+    return;
+  }
+
   console.log(chalk.gray(`${installedCount}/${SKILLS.length} installed at ${skillsDir}`));
   console.log('');
   console.log(chalk.gray('Run `aiskills status` for installation health.'));

package/lib/config.js

@@ -29,6 +29,7 @@ export const REPO_API_URL = 'https://api.github.com/repos/macCesar/aiskills';
 export const SKILLS = [
   'audit-codebase',
   'humaniza',
+  'npm-supply-chain',
   'refactoring-ui',
   'seo-launch',
   'session-log',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.18.1",
+  "version": "1.20.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {

package/skills/humaniza/SKILL.md

@@ -2,6 +2,7 @@
 name: humaniza
 description: 'Editor de estilo para textos en español (especialmente es-MX): quita los tics de escritura de IA y devuelve prosa natural, concreta y directa, sin cambiar el contenido. Úsalo siempre que alguien quiera revisar, pulir o reescribir un texto en español —emails, documentación, marketing, soporte, posts, textos técnicos— aunque nunca diga "humanizar": "esto suena a ChatGPT", "quítale lo robótico", "hazlo más natural", "que no parezca IA", "sonó muy acartonado", "límale el tono", "revísame este correo antes de mandarlo". También cuando el texto mismo trae las señales: rayas por todas partes, "no es X, sino Y", "cabe destacar", listas de tres, abridores como "la verdad es que". No es para: traducir, corregir solo ortografía o gramática, escribir un texto desde cero, ni editar textos en inglés.'
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion
+compatibility: Requires Python 3 (standard library only) for the pattern checker.
 ---
 
 # Humaniza

package/skills/npm-supply-chain/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: npm-supply-chain
+description: 'Publishing to npm and installing from it after the 2025–2026 supply-chain changes: why `npm login` now expires after two hours, classic tokens being gone, granular tokens capped at 90 days and losing direct publish around January 2027, and trusted publishing (OIDC) from GitHub Actions — no stored secret, provenance for free. Also the npm v12 install defaults, where lifecycle scripts, git dependencies and remote tarballs stay off until approved. Use when someone asks why npm demands a login on every publish, wants to publish from CI or GitHub Actions, asks about an NPM_TOKEN, a 2FA-bypass banner on npmjs.com, an OTP prompt, provenance, an `npm install` that broke or stopped running postinstall after an upgrade, or a tag that pushed and never published. Not for: choosing the version number, writing the CHANGELOG, or the release flow itself — that is `/release`.'
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write, AskUserQuestion
+compatibility: Requires Python 3 (standard library only). The audit reads more when git and the gh CLI are available, and degrades cleanly without them.
+---
+
+# npm Supply Chain
+
+How a package gets onto npm and what happens when one comes off it. Two halves of the same registry, both rewritten between November 2025 and July 2026: the credentials that used to sit in a file forever are gone, and the install that used to run a stranger's code by default no longer does.
+
+Ground every answer in the reference files. This is the area where remembered knowledge is most likely to be a year out of date — the token type you remember may have been revoked, and the flag you remember may now default the other way.
+
+Respond in the user's language. This skill is written in English for portability; the report should match whatever language the user is writing in.
+
+## Required workflow (read before responding)
+
+This SKILL.md is an **index**. The dates, the exact fields, the commands and the failure modes live in the reference files. **Reading this file alone is not enough.**
+
+### Step 1 — Open the relevant reference files
+
+| Task involves | Required reading |
+|---|---|
+| `npm login` expiring, session-based auth, classic tokens, granular access tokens, the 90-day cap, 2FA-bypass deprecation, the npmjs.com banner, which actions require interactive 2FA | [references/authentication.md](references/authentication.md) |
+| Publishing from GitHub Actions, OIDC, the trusted-publisher form, `id-token: write`, Node/npm minimums, provenance, `NODE_AUTH_TOKEN` | [references/trusted-publishing.md](references/trusted-publishing.md) |
+| npm v12 install behavior, `allowScripts`, `--allow-git`, `--allow-remote`, `npm approve-scripts`, the committed allowlist, packages that break | [references/install-defaults.md](references/install-defaults.md) |
+| Moving a package off token auth: the order of operations, testing the guard, deleting orphaned secrets, cleaning `~/.npmrc` | [references/migration.md](references/migration.md) |
+| Proving any of the above instead of assuming it: `gh api`, `gh secret list`, reading provenance, querying the registry directly, what npmjs.com shows when OIDC worked | [references/verification.md](references/verification.md) |
+
+### Step 2 — Output contract
+
+Every date, command, field name, version minimum, or registry behavior you cite carries its citation inline:
+
+`[source: references/<file>.md]`
+
+The citation is what separates a value you read from one that merely sounded right — written down, the two look identical, and the reader has no way to tell them apart. Cite while writing rather than collecting sources at the end, because by then you are reconstructing where something came from instead of recording it.
+
+Example: *"Trusted publishing needs Node ≥ 22.14.0 and npm ≥ 11.5.1 on the runner [source: references/trusted-publishing.md]"*
+
+### Step 3 — If you must answer from memory
+
+If you write a claim without having read the reference that backs it, prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it. Dates in this domain moved three times in eighteen months, and a confidently wrong one sends someone to build a credential that no longer works.
+
+### Banned behaviors
+
+- **Inventing a date, a version minimum, or a CLI flag that is not in the references.** The whole point of a dated reference is that "npm requires…" was true of a different npm; a plausible answer here costs the user a broken release, not a wrong opinion.
+- **Recommending a long-lived publish token as the default.** It is the shape the registry is actively retiring, and pointing someone at it builds something they have to dismantle within months.
+- **Reading a secret's value, or writing one into a file, a commit or a log.** You may list secret *names* and check whether anything references them; the value is never yours to handle. A token that appears in a transcript is a token that must be revoked.
+- **Changing a package's npm settings on the user's behalf.** Registering a trusted publisher, editing token settings and changing package access all require an interactive 2FA challenge by design — hand over the exact steps and let the user do them.
+- **Marking the answer complete without listing which reference files you read.** The list is what lets the reader tell a grounded answer from a remembered one.
+
+## Measure the repo before advising it
+
+Run the auditor rather than asking the user what their setup is — most of what matters is readable from disk and from `gh`:
+
+```bash
+python3 <SKILL_DIR>/scripts/auditar_npm.py            # the repo in the current directory
+python3 <SKILL_DIR>/scripts/auditar_npm.py ~/code/foo # somewhere else
+python3 <SKILL_DIR>/scripts/auditar_npm.py --no-network
+```
+
+Replace `<SKILL_DIR>` with the absolute "Base directory for this skill" from the system message that loaded this skill — the working directory here is the user's project, not this one, so a relative `scripts/…` resolves to nothing. The path also differs by install type (`~/.claude/plugins/cache/<plugin>/<version>/skills/npm-supply-chain` for a plugin install, `~/.agents/skills/npm-supply-chain` standalone), so read it rather than assuming it.
+
+It reports: whether `~/.npmrc` and the project `.npmrc` carry a token and whether the registry still accepts it, Actions secrets that look like npm credentials and whether any workflow uses them, which workflows publish and how they authenticate, whether `package.json` and `.claude-plugin/plugin.json` agree on a version, shields.io badges pointing at a package name that does not exist, dependencies with install-time scripts, and the local npm version against v12.
+
+It writes nothing. Everything it finds is a proposal for the user to approve, the same separation `seo-launch` keeps between auditing and installing.
+
+## The shape of the answer
+
+1. **Report what is actually there** — the auditor's output, not a generic checklist.
+2. **Name the deadline that applies**, with its date and source. "This stops working" is only actionable with a when.
+3. **Propose one path**, not a menu. For automated publishing the path is trusted publishing; say so and give the reason rather than laying out three options of which two are dead ends [source: references/authentication.md].
+4. **Split the work by who can do it.** Everything in the repo is yours; everything on npmjs.com needs the user's interactive 2FA [source: references/migration.md].
+5. **Verify afterwards against the registry**, not against the local CLI, and say which command proved it [source: references/verification.md].
+
+## Anti-Patterns
+
+**Credentials**
+
+- Storing a publish token in `~/.npmrc` and treating it as permanent — classic tokens were removed in November 2025 and revoked in December, so the file usually holds a dead string that produces a confusing 401 long before any 2FA prompt [source: references/authentication.md]
+- Reaching for a 2FA-bypass granular token to "stop the login prompts" — it caps at 90 days, it already lost account and package management in July 2026, and it loses direct publish around January 2027 [source: references/authentication.md]
+- Leaving an `NPM_TOKEN` secret in a repo whose workflow no longer uses it. It is a live credential with nothing watching it [source: references/migration.md]
+- Assuming the npmjs.com 2FA-bypass banner is about your account. It is a site-wide campaign notice; the Access Tokens page is what answers whether it applies to you [source: references/authentication.md]
+
+**Trusted publishing**
+
+- Omitting `permissions: id-token: write`. Without it there is no OIDC token to mint, `npm publish` falls back to token auth, and the failure reads like a credentials problem rather than a missing permission [source: references/trusted-publishing.md]
+- Typing the local folder name into the publisher's `Repository` field. The claim is matched against the repository's canonical name on GitHub, which is not always how the folder is spelled on disk [source: references/trusted-publishing.md]
+- Registering the publisher before the workflow file exists on the default branch, or renaming the workflow afterwards. The registration names the file, so the rename breaks publishing until npmjs.com is updated to match [source: references/trusted-publishing.md]
+- Setting `NODE_AUTH_TOKEN` alongside OIDC "just in case". It puts the publish back on token auth and silently gives up provenance [source: references/trusted-publishing.md]
+- Running the publish job on a Node old enough that the npm shipped with it cannot do OIDC — it degrades to token auth instead of erroring clearly [source: references/trusted-publishing.md]
+
+**Installing**
+
+- Upgrading to npm v12 and reading the missing `postinstall` as a broken package. The scripts are off by default now; `npm approve-scripts` is what turns the intended ones back on [source: references/install-defaults.md]
+- Approving every script the prompt lists to make CI green. The allowlist is a security decision that gets committed and inherited by the whole team [source: references/install-defaults.md]
+- Assuming a clean local install means a clean CI install when `ignore-scripts=true` sits in a personal `~/.npmrc`. The machine has been running v12 behavior for years and CI has not [source: references/install-defaults.md]
+
+**Verifying**
+
+- Reporting `npm view <pkg> version` as the state of the registry. The CLI caches it, and it will happily report the previous version minutes after a successful publish [source: references/verification.md]
+- Calling a release published because the tag pushed. The tag starts a workflow; the workflow is what publishes, and it can fail on the version guard, on tests, or on a publisher that was never registered [source: references/verification.md]

package/skills/npm-supply-chain/assets/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to npm
+
+# Publishes when a vX.Y.Z tag is pushed — which is the last thing a release does.
+# Authentication is trusted publishing (OIDC): no NPM_TOKEN, no secrets, no 2FA prompt.
+# The trusted publisher registered on npmjs.com must point at this exact filename,
+# so renaming this file breaks publishing until the registration is updated.
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write # required for OIDC — without it npm publish falls back to token auth
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24' # trusted publishing needs Node >= 22.14.0 and npm >= 11.5.1
+          registry-url: 'https://registry.npmjs.org'
+          # No NODE_AUTH_TOKEN anywhere: setting it puts the publish back on token
+          # auth and gives up provenance.
+
+      # A tag and a manifest can disagree, and npm would publish the manifest's
+      # version under a tag that says something else. This fails before npm ci, so
+      # a mismatched tag never reaches the registry. Add one line per version file
+      # the repo carries — drop the plugin.json block if there is no Claude Code
+      # plugin here.
+      - name: Verify the tag matches every version file
+        run: |
+          echo "node $(node --version) / npm $(npm --version)"
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(node -p "require('./package.json').version")
+          plugin=$(node -p "require('./.claude-plugin/plugin.json').version")
+          echo "tag=$tag  package.json=$pkg  plugin.json=$plugin"
+          [ "$tag" = "$pkg" ] || { echo "::error::tag $tag does not match package.json $pkg"; exit 1; }
+          [ "$tag" = "$plugin" ] || { echo "::error::tag $tag does not match plugin.json $plugin"; exit 1; }
+
+      - run: npm ci
+
+      - run: npm test
+
+      # npm attaches provenance automatically when the publish is authenticated by
+      # OIDC: the published version links back to this commit and this run.
+      - run: npm publish

package/skills/npm-supply-chain/references/authentication.md

@@ -0,0 +1,57 @@
+# Authentication
+
+What proves to npm that a publish is yours. Every long-lived option in this space was removed or put on a clock between November 2025 and January 2027, so the answer to "how do I stop typing my password" is different from what it was a year ago.
+
+## The timeline
+
+| When | What changed |
+|---|---|
+| November 2025 | Classic tokens removed from npm |
+| December 2025 | Classic tokens revoked; `npm login` starts issuing a **two-hour session** instead of a token; CLI token management lands |
+| 8 July 2026 | npm v12 goes GA with the install-time defaults, and the 2FA-bypass GAT deprecation is announced |
+| 31 July 2026 | **Phase 1 applied**: 2FA-bypass tokens lose account, package and organization management |
+| ~January 2027 | **Phase 2 expected**: 2FA-bypass tokens lose the ability to publish directly |
+
+Sources: [npm classic tokens revoked, session-based auth and CLI token management](https://github.blog/changelog/2025-12-09-npm-classic-tokens-revoked-session-based-auth-and-cli-token-management-now-available/), [npm install-time security and GAT bypass2fa deprecation](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/), [Restricting npm bypass-2FA granular access tokens](https://github.blog/changelog/2026-07-31-restricting-npm-bypass-2fa-granular-access-tokens/).
+
+## Why `npm login` keeps coming back
+
+Since December 2025 `npm login` does not write a durable token. It opens a **session that lasts two hours**. Publish inside that window or authenticate again. This is not a token expiring early and there is no setting that extends it — it is the mechanism that replaced classic tokens.
+
+The common symptom is a `401 Unauthorized` from `npm whoami` on a machine that "was logged in", because `~/.npmrc` still holds an `_authToken` line from the old regime that the registry no longer honors. `npm logout` clears it; the stale line is otherwise harmless and only produces confusing errors.
+
+## The three token types, and which are alive
+
+- **Classic tokens** — the long-lived, non-expiring strings people pasted into `.npmrc` and forgot. **Removed November 2025, revoked December 2025.** No flag, option or command brings them back.
+- **Granular access tokens (GATs)** — the only token type still issued. Scoped to specific packages or organizations, with an expiry. **Tokens with write access cap at 90 days**, so a publish token has to be rotated four times a year.
+- **GATs configured to bypass 2FA** — the subset built for unattended CI publishing. These are the ones being retired in two phases (below).
+
+## The 2FA-bypass retirement, in two phases
+
+**Phase 1 — already in effect since 31 July 2026.** A 2FA-bypass GAT can no longer perform sensitive account, package and organization management. Concretely: creating or deleting tokens; generating recovery codes; changing your password, email, profile or 2FA configuration; changing package access, maintainers, or **the trusted publishing configuration**; managing organization and team membership or their package grants. All of those now require an interactive 2FA challenge.
+
+**Phase 2 — expected around January 2027.** The same tokens lose the ability to publish directly. Their publishing surface shrinks to reading private packages and *staging* a publish, where the package only becomes public after a human approves it with 2FA.
+
+**What this does not touch:** GitHub personal access tokens, GitHub App tokens, and the `GITHUB_TOKEN` that Actions injects. The restriction is specific to npm granular access tokens. This clarification came with the 31 July post and was not in the 8 July announcement.
+
+## The banner on npmjs.com
+
+The 2FA-bypass notice shown when you log into npmjs.com is a **site-wide campaign banner**, not a diagnosis of the account looking at it. It appears whether or not you own a single bypass token.
+
+To answer whether it applies: npmjs.com → avatar → **Access Tokens**, and read the **Bypass 2FA** column. An empty list, or a list where that column is blank on every row, means the deprecation does not touch the account at all. Expired tokens still show in that list and are worth deleting — a token that expired months ago is noise, and noise is what hides the one that matters.
+
+## The three remaining paths
+
+| Option | Friction per release | Lifetime |
+|---|---|---|
+| **A. Interactive** — `npm login`, then publish | one login (plus an OTP per publish) | indefinite |
+| **B. GAT with 2FA bypass** in `~/.npmrc` | none | **90 days max**, and direct publish dies ~January 2027 |
+| **C. Trusted publishing (OIDC)** from Actions | none | indefinite; the registry's own recommendation |
+
+**B is the option the deprecation exists to discourage**: a long-lived secret on disk, renewable four times a year, with a known end date. Building it now means dismantling it within months.
+
+**C is the only one that returns zero friction without an expiry.** See [trusted-publishing.md](trusted-publishing.md). A is a perfectly good fallback and stays available forever — if OIDC fails for any reason, `npm login` and a manual publish still work.
+
+## Package-level hardening
+
+npm can mark a package **"Require two-factor authentication and disallow tokens"**, which rejects any token regardless of its own configuration. On a package published by hand (option A) this is free protection. Its interaction with OIDC publishing is **not established here** — do not enable it on a package that publishes through trusted publishing without confirming the two coexist.

package/skills/npm-supply-chain/references/install-defaults.md

@@ -0,0 +1,43 @@
+# Install defaults in npm v12
+
+npm v12 went generally available and became `latest` on 8 July 2026. It turns on the install-time security defaults announced in June: three things that used to happen automatically during `npm install` are now opt-in.
+
+Source: [npm install-time security and GAT bypass2fa deprecation](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/).
+
+## What changed
+
+| Before | npm v12 |
+|---|---|
+| Dependency lifecycle scripts (`preinstall`, `install`, `postinstall`) and implicit node-gyp builds ran automatically | **Do not run** unless explicitly allowed (`allowScripts` defaults to off) |
+| Git dependencies (`github:user/repo`), direct or transitive, resolved | **Not resolved** unless allowed (`--allow-git` defaults to none) |
+| Dependencies from remote URLs (an `https://` tarball) resolved | **Not resolved** unless allowed (`--allow-remote` defaults to none) |
+
+The reason is the ecosystem's most exploited vector: a compromised package put its payload in a `postinstall` and ran it on your machine as a side effect of `npm install`. That code is now inert until someone approves it.
+
+All three were available behind warnings from **npm 11.16.0**, so a project can be rehearsed against the new behavior before upgrading the major.
+
+## The migration flow
+
+```bash
+npm approve-scripts --allow-scripts-pending
+```
+
+It lists the packages asking to run install scripts. Approve the ones you trust, and **commit the resulting allowlist in `package.json`** so the team and CI inherit the same decision rather than each machine answering the prompt differently.
+
+Two things about that allowlist: it is a security decision, not a build chore — approving everything the prompt offers to make CI green defeats the change entirely — and it is inherited, so whoever commits it is deciding for everyone.
+
+## What actually breaks
+
+Nothing in a dependency tree of pure JavaScript. The packages that notice are the ones that **download or compile a binary during install**: `sharp`, `puppeteer`, native CLI wrappers, anything using node-gyp. In a Laravel or Vite project the symptom shows up one step removed — assets that stop compiling after a clean `npm ci`.
+
+The way to know without guessing is to run `npm approve-scripts --allow-scripts-pending` in each repo and read the list. A package whose `package.json` declares no `preinstall` / `install` / `postinstall` and pulls no node-gyp dependency has nothing to approve, and its users see no prompt at all.
+
+## The trap: a personal `ignore-scripts`
+
+A developer with `ignore-scripts=true` in `~/.npmrc` has been living with the main v12 behavior for years and will not notice the upgrade at all. Their CI, running with the default configuration, has not — so "it installs fine on my machine" is not evidence about the pipeline, in either direction.
+
+Check both: the personal `~/.npmrc`, the project `.npmrc`, and what the CI job actually runs. Only the last one describes what users and the pipeline experience.
+
+## As a package author
+
+The question is what your *dependents* see. If none of your dependencies declares an install script, a user on npm v12 installs your package without a single approval prompt. This is worth measuring before publishing rather than after an issue arrives: the auditor in this skill reports it, and so does reading the `scripts` block of every installed `package.json`.