@maccesar/aiskills 1.18.1 → 1.19.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,6 +494,48 @@ 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
@@ -688,19 +731,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/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/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.19.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`.

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

@@ -0,0 +1,57 @@
+# Migrating a package to trusted publishing
+
+Done once per package. The order matters, because two of the steps can only be done by the package owner with an interactive 2FA challenge, and one of them is easy to test cheaply before it can cost a bad publish.
+
+## 1. Audit what is there
+
+Before changing anything, establish the starting state — this is what `scripts/auditar_npm.py` reports, and each finding maps to a step below:
+
+- **Tokens on disk**: `~/.npmrc` and any project `.npmrc`. An `_authToken` line from before December 2025 is dead weight producing confusing 401s [source: authentication.md].
+- **Actions secrets**: anything named like an npm credential (`NPM_TOKEN` and variants). A secret no workflow references is orphaned — a live credential with nothing watching it.
+- **Existing workflows**: which ones publish, and whether they authenticate with a token or with OIDC.
+- **Version files**: `package.json`, and `.claude-plugin/plugin.json` if the repo also ships a Claude Code plugin. They feed the guard in step 2.
+- **Install-time scripts** in the dependency tree, which is a different question but the same audit [source: install-defaults.md].
+
+## 2. Add the workflow and push it
+
+Copy `assets/publish.yml`, adjust the version files in the guard to match the repo, commit, push to the default branch. Details of each line are in [trusted-publishing.md](trusted-publishing.md).
+
+The file must be on GitHub before the registration points at it, and before any tag is pushed.
+
+## 3. Register the trusted publisher
+
+npmjs.com → the package → **Settings → Trusted Publisher → GitHub Actions**, with the four fields from [trusted-publishing.md](trusted-publishing.md). Read the repository name from the GitHub API rather than from the local folder name — see [verification.md](verification.md) for the command.
+
+**Only the package owner can do this**, interactively, with 2FA. It is one of the operations 2FA-bypass tokens lost in July 2026 [source: authentication.md]. Hand over the exact field values; do not attempt it on their behalf.
+
+If the package is configured as *"Require two-factor authentication and disallow tokens"*, leave that setting alone. Whether it coexists with OIDC publishing is not established here.
+
+## 4. Test the guard before trusting it
+
+The version guard is the one part of the workflow that can be verified without publishing anything. Run its logic locally against a tag that should pass and one that should fail:
+
+```bash
+tag="1.18.1"; node -p "require('./package.json').version"     # expect a match
+tag="9.9.9";  node -p "require('./package.json').version"     # expect a mismatch → the job must exit 1
+```
+
+A guard that passes everything is not a guard. Confirm both directions before relying on it — the same discipline as running a positive control on any measuring instrument.
+
+## 5. First real release
+
+Push a tag and watch the run rather than assuming it. The verification commands are in [verification.md](verification.md). Three things distinguish a real success from a plausible one: the workflow run is green, the registry (not the local CLI cache) reports the new version, and npmjs.com lists the publisher as **GitHub Actions** rather than a username.
+
+If it fails, nothing is lost: `npm login` plus a manual publish is still the fallback, and it stays available permanently [source: authentication.md].
+
+## 6. Clean up what the old flow left behind
+
+- **Orphaned Actions secrets.** `gh secret delete NPM_TOKEN --repo <owner>/<repo>` once nothing references it. An unused publish credential is strictly a liability.
+- **Dead `_authToken` in `~/.npmrc`.** `npm logout` removes it. Not dangerous, but it is what makes `npm whoami` answer 401 on a machine that looks logged in.
+- **Empty workflow directories** left by a removed CI file, and any documentation that still tells the reader to run `npm publish` by hand or to set a token.
+- **Expired tokens on npmjs.com.** They do nothing, and they hide the one entry that matters in the list.
+
+Delete secrets only with the user's agreement, and never print a secret's value — listing names is enough to reason about orphans.
+
+## What the release flow becomes
+
+`/release` still does everything it did: semantic commits, version bump, CHANGELOG, tag, push. The publish is what moved — it now happens because the tag landed, not because someone typed `npm publish`. Nothing needs to run by hand, and the release is not finished until that workflow run is green.

package/skills/npm-supply-chain/references/trusted-publishing.md

@@ -0,0 +1,79 @@
+# Trusted publishing (OIDC)
+
+The runner proves who it is instead of carrying a secret. GitHub Actions mints a short-lived OIDC credential describing the exact repository, workflow and ref that is running; npm checks that description against the trusted publisher registered for the package and, if it matches, accepts the publish. Nothing is stored anywhere: there is no token to rotate, no secret to leak, no session to keep alive.
+
+Two consequences worth stating up front: **provenance is attached automatically** to a publish made this way — npm links the published version to the exact commit and workflow run — and the registry records the publisher as **GitHub Actions** rather than a person.
+
+## The registration on npmjs.com
+
+Per package, under **Settings → Trusted Publisher → GitHub Actions**:
+
+| Field | Value |
+|---|---|
+| Organization or user | the GitHub owner, e.g. `macCesar` |
+| Repository | the repository name **as GitHub spells it** |
+| Workflow filename | the file's basename with extension, e.g. `publish.yml` |
+| Environment | empty, unless the job declares `environment:` |
+
+Three ways this goes wrong:
+
+- **The `Repository` field is the canonical repository name, not the local folder name.** A project cloned into `~/Developer/TiTools` can live at `github.com/macCesar/titools`; the OIDC claim carries the canonical one, and a mismatch fails the publish with an authorization error that says nothing about capitalization. Read it from the API rather than from the filesystem — see [verification.md](verification.md).
+- **The workflow filename must match exactly**, extension included. Renaming the file later breaks publishing until the registration on npmjs.com is updated, and the break surfaces only on the next release.
+- **Registering it requires an interactive 2FA challenge.** Changing the trusted publishing configuration is one of the operations 2FA-bypass tokens lost on 31 July 2026 [source: authentication.md]. This is a step only the package owner can do; it cannot be automated or done on their behalf.
+
+## Order of operations
+
+1. Commit and **push the workflow to the default branch** first. The registration points at a file; the file should exist.
+2. Register the publisher on npmjs.com.
+3. Push a tag.
+
+Doing 2 before 1 is not fatal, but it leaves a registration pointing at nothing and the first release fails for a reason that looks like the registration is wrong.
+
+## The workflow
+
+The template lives at `assets/publish.yml` in this skill. The parts that matter:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write   # without this there is no OIDC token and npm falls back to token auth
+```
+
+`id-token: write` is the whole switch. Omit it and the publish does not error with "you forgot a permission" — it degrades to looking for a token, finds none, and fails as a credentials problem.
+
+```yaml
+- uses: actions/setup-node@v7
+  with:
+    node-version: '24'
+    registry-url: 'https://registry.npmjs.org'
+```
+
+**Minimums: Node ≥ 22.14.0 and npm ≥ 11.5.1.** Older combinations do not know how to present the OIDC credential and quietly fall back to token auth. `registry-url` is what makes `setup-node` write the `.npmrc` pointing at the public registry.
+
+**Do not set `NODE_AUTH_TOKEN`.** It is the environment variable `setup-node` wires up for token auth; present, it puts the publish back on a secret and gives up provenance. A trusted-publishing workflow has no `env:` block on the publish step and no `secrets.*` reference anywhere.
+
+Pin the actions. `actions/checkout` and `actions/setup-node` are on v7 as of August 2026.
+
+## The version guard
+
+The template compares the pushed tag against every version file in the repo before publishing anything:
+
+```bash
+tag="${GITHUB_REF_NAME#v}"
+pkg=$(node -p "require('./package.json').version")
+[ "$tag" = "$pkg" ] || { echo "::error::tag $tag does not match package.json $pkg"; exit 1; }
+```
+
+It exists because a tag and a manifest can disagree and npm will happily publish the manifest's version under a tag that says something else. In a repo that also ships a Claude Code plugin, `.claude-plugin/plugin.json` is a second version file and belongs in the same check — TiTools published 2.6.0 to npm while its `plugin.json` still read 3.0.0, and the marketplace announced a version that did not exist.
+
+Costs one step, removes the whole class of mistake, and fails before `npm ci` so a bad tag never reaches the registry.
+
+## What the release flow looks like afterwards
+
+```
+/release  →  creates the tag and pushes it  →  Actions publishes
+```
+
+No `npm login`, no two-hour session, no OTP. The human checkpoint does not disappear; it moves to the tag, which is still created deliberately after reviewing the diff.
+
+If a publish fails for any reason, nothing is trapped: `npm login` and a manual `npm publish` remain available as they always were [source: authentication.md].

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

@@ -0,0 +1,84 @@
+# Verification
+
+Every claim in this area is checkable in one command, which is the reason none of them should be asserted from memory. This file is the list of those commands and, for each, what a wrong answer looks like.
+
+## The repository's canonical name
+
+The trusted publisher matches the repository as GitHub spells it, which is not necessarily how the folder is spelled on disk:
+
+```bash
+gh api repos/<owner>/<repo> --jq .full_name
+```
+
+Run it before handing the user any value to type into a form. A folder named `TiTools` whose repository is `macCesar/titools` produces an OIDC claim that never matches a registration typed from the filesystem, and the resulting failure says nothing about capitalization.
+
+This is the general rule for anything the user has to copy by hand: verify the exact string first, then hand it over.
+
+## Credentials, without reading them
+
+```bash
+gh secret list --repo <owner>/<repo>          # names and dates only, never values
+grep -rl "secrets\." .github/workflows/       # which workflows reference any secret
+npm whoami                                    # 401 means the local session or token is dead
+```
+
+A secret that appears in `gh secret list` and in no workflow is orphaned. Names and timestamps are enough to establish that; the value is never needed and must never be printed.
+
+## Whether a workflow publishes, and how
+
+```bash
+grep -l "npm publish" .github/workflows/*.yml
+grep -n "id-token\|NODE_AUTH_TOKEN\|NPM_TOKEN" .github/workflows/*.yml
+```
+
+`id-token: write` present and no token reference means OIDC. A `NODE_AUTH_TOKEN` or `NPM_TOKEN` reference means token auth, regardless of what the file is named or what a comment claims.
+
+## The registry, not the CLI cache
+
+```bash
+npm view <pkg> version            # ← do not report this as the state of the registry
+curl -s https://registry.npmjs.org/<pkg> | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['dist-tags'])"
+```
+
+**`npm view` is cached and it lies.** Measured on 2026-08-14: minutes after `@maccesar/aiskills` 1.18.1 published successfully, the local `npm view` still answered 1.18.0 while a direct request to the registry already returned 1.18.1. Reporting the cached answer as a failed publish sends someone to debug a release that worked.
+
+For a scoped package the URL encodes the slash: `https://registry.npmjs.org/@maccesar%2Faiskills`.
+
+## Provenance and the publisher
+
+```bash
+npm view <pkg> --json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('dist',{}).get('attestations'))"
+```
+
+The visual signal is stronger and takes one glance: on npmjs.com, the package's version list shows **`GitHub Actions`** in the publisher column where a manually published package shows a username. That is trusted publishing made visible — npm recorded that a workflow identified by OIDC uploaded the package — and it is what backs the provenance badge.
+
+## The workflow run behind a tag
+
+A pushed tag is not a publish. It starts a run, and the run can fail on the version guard, on the tests, or on a publisher that was never registered:
+
+```bash
+gh run watch                                  # follow the run started by the tag
+gh run list --workflow=publish.yml --limit 5  # after the fact
+```
+
+A release is finished when that run is green and the registry confirms the version — not when `git push origin v1.2.3` returns.
+
+## Badges
+
+A shields.io badge asks the registry for a package by name. If the name is wrong the badge renders "package not found" rather than erroring, so a broken badge survives for months:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" https://registry.npmjs.org/<name-exactly-as-the-badge-spells-it>
+```
+
+The failure mode is specific to **scoped packages**: a README badge that says `npm/dm/aiskills` for a package published as `@maccesar/aiskills` looks plausible and reports nothing. It hid a real number here — 568 downloads per month — across three badges for months. An unscoped package cannot have this bug, since the badge name and the package name are the same string.
+
+npmjs.com renders the README of the **published version**, so correcting a badge requires a release, not just a push to the default branch.
+
+## Install-time scripts in the tree
+
+```bash
+npm approve-scripts --allow-scripts-pending          # authoritative: what npm itself would ask about
+```
+
+Reading each dependency's `scripts` block is the offline approximation and is what the auditor in this skill does; the command above is what npm actually evaluates [source: install-defaults.md].

package/skills/npm-supply-chain/scripts/auditar_npm.py

@@ -0,0 +1,509 @@
+#!/usr/bin/env python3
+"""Audit how a repository publishes to npm and what it installs from it.
+
+Reads the repo, the npm configuration and the GitHub Actions setup, and reports
+the state of each: credentials on disk, orphaned Actions secrets, how the
+publishing workflow authenticates, version files that disagree, README badges
+pointing at a package that does not exist, dependencies that run scripts at
+install time, and the local npm version against v12.
+
+    python3 auditar_npm.py                 # the repo in the current directory
+    python3 auditar_npm.py ~/code/foo
+    python3 auditar_npm.py --no-network    # skip the registry and gh lookups
+
+Writes nothing. Every finding is a proposal for the user to approve.
+
+Standard library only: runs on any macOS or Linux with Python 3.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+OK, FALTA, REVISAR, INFO = "ok", "falta", "revisar", "info"
+
+SIMBOLO = {OK: "  ok  ", FALTA: " MISS ", REVISAR: "CHECK ", INFO: " info "}
+
+# Names that look like an npm publishing credential. Matched case-insensitively
+# against secret names; the value of a secret is never read, here or anywhere.
+PATRON_SECRETO_NPM = re.compile(r"NPM.*(TOKEN|AUTH|PUBLISH)|(TOKEN|AUTH).*NPM", re.I)
+
+# The first npm version whose install-time defaults are the ones described in
+# references/install-defaults.md.
+NPM_V12 = 12
+
+CONSULTAR_RED = True
+
+
+# ---------------------------------------------------------------- utilities
+
+
+def correr(comando: list[str], tiempo: int = 20) -> tuple[int, str]:
+    """Run a command and return (exit code, stdout). 127 means it is not installed."""
+    try:
+        r = subprocess.run(
+            comando, capture_output=True, text=True, timeout=tiempo, check=False
+        )
+        return r.returncode, r.stdout.strip()
+    except FileNotFoundError:
+        return 127, ""
+    except subprocess.TimeoutExpired:
+        return 124, ""
+
+
+def existe(programa: str) -> bool:
+    return correr([programa, "--version"], tiempo=10)[0] not in (127, 124)
+
+
+def leer_json(ruta: Path) -> dict | None:
+    try:
+        return json.loads(ruta.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def leer_texto(ruta: Path) -> str:
+    try:
+        return ruta.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return ""
+
+
+def pedir(url: str, tiempo: int = 10) -> int | None:
+    """HTTP status of a URL, or None if it could not be reached."""
+    if not CONSULTAR_RED:
+        return None
+    peticion = urllib.request.Request(url, headers={"User-Agent": "auditar_npm"})
+    try:
+        with urllib.request.urlopen(peticion, timeout=tiempo) as r:
+            return r.status
+    except urllib.error.HTTPError as e:
+        return e.code
+    except Exception:
+        return None
+
+
+class Reporte:
+    """Collects findings by section and prints them once, so the output reads as
+    a report rather than as a log of the order the checks happened to run in."""
+
+    def __init__(self) -> None:
+        self.secciones: list[tuple[str, list[tuple[str, str, str]]]] = []
+
+    def abrir(self, titulo: str) -> None:
+        self.secciones.append((titulo, []))
+
+    def add(self, estado: str, etiqueta: str, detalle: str = "") -> None:
+        if not self.secciones:
+            self.abrir("General")
+        self.secciones[-1][1].append((estado, etiqueta, detalle))
+
+    def imprimir(self) -> int:
+        faltantes = 0
+        for titulo, filas in self.secciones:
+            if not filas:
+                continue
+            print(f"\n{titulo}")
+            print("-" * len(titulo))
+            for estado, etiqueta, detalle in filas:
+                faltantes += estado == FALTA
+                linea = f"[{SIMBOLO[estado]}] {etiqueta}"
+                if detalle:
+                    linea += f" — {detalle}"
+                print(linea)
+        print()
+        return faltantes
+
+
+# ---------------------------------------------------------------- checks
+
+
+def revisar_npmrc(proyecto: Path, r: Reporte) -> None:
+    """Credentials on disk, and whether the registry still accepts them.
+
+    A token line is reported by its presence only. Reading or printing the value
+    would put a live credential in a transcript, which is how a token becomes one
+    that has to be revoked.
+    """
+    r.abrir("npm configuration")
+
+    for etiqueta, ruta in (
+        ("~/.npmrc", Path.home() / ".npmrc"),
+        (".npmrc (project)", proyecto / ".npmrc"),
+    ):
+        if not ruta.exists():
+            r.add(INFO, etiqueta, "not present")
+            continue
+
+        texto = leer_texto(ruta)
+        if re.search(r"^\s*(//.*:)?_auth(Token)?\s*=", texto, re.M):
+            r.add(
+                REVISAR,
+                f"{etiqueta}: token line",
+                "an _authToken is present. Classic tokens were revoked in Dec 2025; "
+                "if this predates that, it is dead weight producing 401s (npm logout)",
+            )
+        else:
+            r.add(OK, f"{etiqueta}: no token line", "")
+
+        if re.search(r"^\s*ignore-scripts\s*=\s*true", texto, re.M):
+            r.add(
+                INFO,
+                f"{etiqueta}: ignore-scripts=true",
+                "this machine already behaves like npm v12; CI probably does not",
+            )
+
+    if CONSULTAR_RED and existe("npm"):
+        codigo, salida = correr(["npm", "whoami"])
+        if codigo == 0 and salida:
+            r.add(OK, "npm session", f"authenticated as {salida}")
+        else:
+            r.add(
+                INFO,
+                "npm session",
+                "not authenticated (npm login opens a two-hour session; "
+                "irrelevant if publishing happens from Actions)",
+            )
+
+
+def version_npm(r: Reporte) -> None:
+    r.abrir("npm version")
+
+    codigo, salida = correr(["npm", "--version"])
+    if codigo != 0 or not salida:
+        r.add(REVISAR, "npm", "not found on PATH")
+        return
+
+    try:
+        mayor = int(salida.split(".")[0])
+    except ValueError:
+        r.add(INFO, "npm", salida)
+        return
+
+    if mayor >= NPM_V12:
+        r.add(OK, "npm", f"{salida} — install-time defaults are on")
+    else:
+        r.add(
+            INFO,
+            "npm",
+            f"{salida} — v12 defaults not applied yet; 11.16.0+ warns about them first",
+        )
+
+
+def repo_github(proyecto: Path) -> str | None:
+    """owner/repo as GitHub spells it, read from the API rather than the folder name."""
+    codigo, salida = correr(
+        ["git", "-C", str(proyecto), "remote", "get-url", "origin"]
+    )
+    if codigo != 0 or not salida:
+        return None
+
+    m = re.search(r"github\.com[:/]+([^/]+)/(.+?)(?:\.git)?$", salida)
+    if not m:
+        return None
+    local = f"{m.group(1)}/{m.group(2)}"
+
+    if CONSULTAR_RED and existe("gh"):
+        codigo, canonico = correr(["gh", "api", f"repos/{local}", "--jq", ".full_name"])
+        if codigo == 0 and canonico:
+            return canonico
+    return local
+
+
+def revisar_secretos(proyecto: Path, repo: str | None, r: Reporte) -> None:
+    """Actions secrets that look like npm credentials, and whether anything uses them."""
+    r.abrir("GitHub Actions secrets")
+
+    if not repo:
+        r.add(INFO, "repository", "no GitHub remote — skipping")
+        return
+    if not CONSULTAR_RED:
+        r.add(INFO, "secrets", "skipped (--no-network)")
+        return
+    if not existe("gh"):
+        r.add(INFO, "secrets", "gh is not installed — cannot list them")
+        return
+
+    codigo, salida = correr(["gh", "secret", "list", "--repo", repo])
+    if codigo != 0:
+        r.add(INFO, "secrets", f"could not read them for {repo}")
+        return
+
+    nombres = [l.split()[0] for l in salida.splitlines() if l.strip()]
+    sospechosos = [n for n in nombres if PATRON_SECRETO_NPM.search(n)]
+
+    if not sospechosos:
+        r.add(OK, "no npm credentials stored", f"{len(nombres)} secret(s) in {repo}")
+        return
+
+    usados = leer_texto_workflows(proyecto)
+    for nombre in sospechosos:
+        if nombre in usados:
+            r.add(
+                REVISAR,
+                f"secret {nombre}",
+                "referenced by a workflow — token auth, replaceable by OIDC",
+            )
+        else:
+            r.add(
+                FALTA,
+                f"secret {nombre} is orphaned",
+                f"no workflow references it. gh secret delete {nombre} --repo {repo}",
+            )
+
+
+def leer_texto_workflows(proyecto: Path) -> str:
+    carpeta = proyecto / ".github" / "workflows"
+    if not carpeta.is_dir():
+        return ""
+    return "\n".join(sin_comentarios(leer_texto(f)) for f in sorted(carpeta.glob("*.y*ml")))
+
+
+def sin_comentarios(texto: str) -> str:
+    """YAML with its comments removed.
+
+    A well-commented trusted-publishing workflow explains that it carries no
+    NPM_TOKEN — and reading that sentence as a credential reference is exactly
+    how a correct file gets reported as broken.
+    """
+    texto = re.sub(r"(?m)^\s*#.*$", "", texto)
+    return re.sub(r"(?m)\s#.*$", "", texto)
+
+
+def revisar_workflows(proyecto: Path, r: Reporte) -> None:
+    """Which workflow publishes, and how it proves who it is."""
+    r.abrir("Publishing workflow")
+
+    carpeta = proyecto / ".github" / "workflows"
+    archivos = sorted(carpeta.glob("*.y*ml")) if carpeta.is_dir() else []
+
+    # A package.json marked private is an application or a toolchain, not
+    # something that gets published — the absence of a publishing workflow is
+    # the correct state, not a finding.
+    pkg = leer_json(proyecto / "package.json") or {}
+    if pkg.get("private") is True:
+        r.add(INFO, "private package", "never published; nothing to automate")
+        return
+
+    if not archivos:
+        r.add(
+            FALTA,
+            "no workflow publishes this package",
+            "every release needs an interactive login (two-hour session). "
+            "See references/trusted-publishing.md",
+        )
+        return
+
+    publicadores = [f for f in archivos if "npm publish" in sin_comentarios(leer_texto(f))]
+    if not publicadores:
+        r.add(
+            FALTA,
+            "no workflow runs npm publish",
+            f"{len(archivos)} workflow(s) present, none publishes",
+        )
+        return
+
+    for archivo in publicadores:
+        texto = sin_comentarios(leer_texto(archivo))
+        nombre = archivo.name
+
+        oidc = re.search(r"^\s*id-token:\s*write", texto, re.M)
+        token = re.search(r"NODE_AUTH_TOKEN|NPM_TOKEN|secrets\.\w*NPM", texto)
+
+        if oidc and not token:
+            r.add(OK, f"{nombre}: OIDC", "trusted publishing, no stored secret")
+        elif oidc and token:
+            r.add(
+                REVISAR,
+                f"{nombre}: OIDC and a token",
+                "a token reference puts the publish back on token auth and drops provenance",
+            )
+        elif token:
+            r.add(
+                FALTA,
+                f"{nombre}: token auth",
+                "long-lived credential; 2FA-bypass tokens lose direct publish ~Jan 2027",
+            )
+        else:
+            r.add(REVISAR, f"{nombre}: no visible credential", "check how it authenticates")
+
+        if re.search(r"tags:\s*$|-\s*['\"]?v\*", texto, re.M):
+            r.add(OK, f"{nombre}: trigger", "runs on a pushed tag")
+        else:
+            r.add(REVISAR, f"{nombre}: trigger", "does not look tag-driven")
+
+        if not re.search(r"GITHUB_REF_NAME|github\.ref_name", texto):
+            r.add(
+                REVISAR,
+                f"{nombre}: no version guard",
+                "nothing compares the tag against the version files before publishing",
+            )
+
+
+def revisar_paquete(proyecto: Path, r: Reporte) -> None:
+    """The manifest itself: scope, and version files that must agree."""
+    r.abrir("Package manifest")
+
+    pkg = leer_json(proyecto / "package.json")
+    if not pkg:
+        r.add(INFO, "package.json", "not an npm project")
+        return
+
+    nombre = pkg.get("name", "")
+    version = pkg.get("version", "")
+    r.add(INFO, "package", f"{nombre}@{version}")
+
+    if nombre.startswith("@"):
+        r.add(
+            INFO,
+            "scoped package",
+            "badges and registry URLs must carry the scope; the unscoped name is a different package",
+        )
+
+    plugin_path = proyecto / ".claude-plugin" / "plugin.json"
+    if plugin_path.exists():
+        plugin = leer_json(plugin_path) or {}
+        if plugin.get("version") == version:
+            r.add(OK, "plugin.json version", f"in sync at {version}")
+        else:
+            r.add(
+                FALTA,
+                "plugin.json is out of sync",
+                f"package.json {version} vs plugin.json {plugin.get('version')} — "
+                "marketplace users keep the cached old code",
+            )
+
+
+def revisar_badges(proyecto: Path, r: Reporte) -> None:
+    """shields.io badges asking the registry for a package name that does not exist.
+
+    The failure is silent: shields renders "package not found" instead of an error,
+    so a broken badge survives for months and hides whatever it was reporting.
+    """
+    r.abrir("README badges")
+
+    readme = proyecto / "README.md"
+    if not readme.exists():
+        r.add(INFO, "README.md", "not present")
+        return
+
+    texto = leer_texto(readme)
+    nombres = set(re.findall(r"img\.shields\.io/npm/[a-z]+/([^)\s\]]+)", texto))
+    if not nombres:
+        r.add(INFO, "npm badges", "none")
+        return
+
+    pkg = leer_json(proyecto / "package.json") or {}
+    esperado = pkg.get("name", "")
+
+    for crudo in sorted(nombres):
+        nombre = crudo.replace("%2F", "/").rstrip("?").split("?")[0]
+        if esperado and nombre == esperado:
+            r.add(OK, f"badge {nombre}", "matches package.json")
+            continue
+
+        estado = pedir(f"https://registry.npmjs.org/{nombre.replace('/', '%2F')}")
+        if estado == 200:
+            r.add(REVISAR, f"badge {nombre}", f"resolves, but package.json says {esperado}")
+        elif estado is None:
+            r.add(REVISAR, f"badge {nombre}", f"could not verify; package.json says {esperado}")
+        else:
+            r.add(
+                FALTA,
+                f"badge {nombre} points at nothing",
+                f"registry answers {estado}; this package is {esperado}",
+            )
+
+
+def revisar_scripts_instalacion(proyecto: Path, r: Reporte) -> None:
+    """What a user on npm v12 would be asked to approve when installing this tree."""
+    r.abrir("Install-time scripts (npm v12)")
+
+    modulos = proyecto / "node_modules"
+    if not modulos.is_dir():
+        r.add(INFO, "node_modules", "not installed — run npm install to measure this")
+        return
+
+    con_scripts: list[str] = []
+    node_gyp: list[str] = []
+
+    for manifiesto in modulos.glob("*/package.json"):
+        datos = leer_json(manifiesto)
+        if not datos:
+            continue
+        scripts = datos.get("scripts") or {}
+        if any(k in scripts for k in ("preinstall", "install", "postinstall")):
+            con_scripts.append(datos.get("name", manifiesto.parent.name))
+        if "node-gyp" in json.dumps(datos.get("dependencies") or {}):
+            node_gyp.append(datos.get("name", manifiesto.parent.name))
+
+    # Scoped packages live one level deeper.
+    for manifiesto in modulos.glob("@*/*/package.json"):
+        datos = leer_json(manifiesto)
+        if not datos:
+            continue
+        scripts = datos.get("scripts") or {}
+        if any(k in scripts for k in ("preinstall", "install", "postinstall")):
+            con_scripts.append(datos.get("name", manifiesto.parent.name))
+
+    if not con_scripts and not node_gyp:
+        r.add(OK, "no dependency runs install scripts", "npm v12 installs this cleanly")
+        return
+
+    for nombre in sorted(set(con_scripts)):
+        r.add(REVISAR, f"{nombre} declares an install script", "needs approval on npm v12")
+    for nombre in sorted(set(node_gyp) - set(con_scripts)):
+        r.add(REVISAR, f"{nombre} pulls node-gyp", "implicit build, off by default on npm v12")
+
+    r.add(
+        INFO,
+        "authoritative check",
+        "npm approve-scripts --allow-scripts-pending, then commit the allowlist",
+    )
+
+
+def main() -> int:
+    global CONSULTAR_RED
+
+    p = argparse.ArgumentParser(
+        description="Audit how a repository publishes to npm and what it installs from it."
+    )
+    p.add_argument("ruta", nargs="?", default=".", help="project directory (default: .)")
+    p.add_argument(
+        "--no-network",
+        action="store_true",
+        help="skip the registry, gh and npm whoami lookups",
+    )
+    args = p.parse_args()
+
+    CONSULTAR_RED = not args.no_network
+
+    proyecto = Path(os.path.expanduser(args.ruta)).resolve()
+    if not proyecto.is_dir():
+        p.error(f"{args.ruta} is not a directory")
+
+    print(f"\nnpm supply-chain audit of {proyecto}")
+
+    r = Reporte()
+    version_npm(r)
+    revisar_npmrc(proyecto, r)
+    revisar_paquete(proyecto, r)
+    revisar_workflows(proyecto, r)
+    revisar_secretos(proyecto, repo_github(proyecto), r)
+    revisar_badges(proyecto, r)
+    revisar_scripts_instalacion(proyecto, r)
+
+    faltan = r.imprimir()
+    return 1 if faltan else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/refactoring-ui/SKILL.md

@@ -25,10 +25,12 @@ The SKILL.md alone is an **index** of references. The detail you need to give ac
 
 ### Step 2 — Output contract
 
-Every design recommendation, ratio, value, or rule you cite MUST be backed by a citation in the form:
+Every design recommendation, ratio, value, or rule 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: *"Use weight and color, not just font size, to establish hierarchy [source: references/02-page-mechanics.md]"*
 
 ### Step 3 — If you must answer from memory

package/skills/seo-launch/SKILL.md

@@ -2,6 +2,7 @@
 name: seo-launch
 description: 'Audit and then install everything a site needs to be indexed and to render a proper card when its link is shared: head tags, Open Graph and Twitter card, the 1200x630 og:image, favicon and apple-touch-icon, robots.txt, sitemap.xml, an .htaccess with one canonical domain, JSON-LD, and the Search Console handover. Works on static sites and on Laravel or plain PHP projects. Use when the user says the link shows a grey box with no preview in WhatsApp, asks why Google cannot find the site, is putting a new domain live, or asks for an SEO review, meta tags, og:image, sitemap or robots.txt — even when they never say "SEO". Not for: keyword research, writing the content itself, backlinks, paid ads, or analytics dashboards.'
 allowed-tools: Read, Grep, Glob, Bash, Edit, Write, AskUserQuestion
+compatibility: Requires Python 3 (standard library only) and network access to audit a live site. Stage 2 uses ImageMagick to generate the images.
 ---
 
 # SEO Launch

package/skills/stitch-showcase/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: stitch-showcase
 description: 'Turns Google Stitch design exports (zips holding `code.html` + `screen.png`) into a navigable showcase — gallery, viewer, component catalog — in about three seconds, and enriches it on demand. Use this for anything involving those exports: "organiza mis diseños de Stitch", "arma el muestrario", "organize my Stitch designs", "build the showcase", "tengo los zips de Stitch", "mis exports de Stitch", or a bare path to a folder of design zips. Also for maintaining one that already exists: "optimiza el showcase", "mejora las descripciones", "agrega estas pantallas nuevas", "el cliente pidió otra pantalla", "estandariza los navbars", "make all the footers the same". Not for: Figma or Sketch exports, loose screenshots, redesigning the screens themselves, or building the real app from them.'
+compatibility: Requires Python 3 (standard library only) to extract the zips and build the showcase.
 ---
 
 # stitch-showcase

package/skills/vscode-extension-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vscode-extension-dev
-description: 'VS Code extension development grounded in the official Extension API docs. Use this whenever someone is creating, scaffolding, debugging, testing, bundling or publishing a VS Code extension — TreeView, QuickPick, Webview, StatusBar, SecretStorage, Language Server Protocol, Debug Adapter Protocol, notebooks — and also when they never say "extension" but the work clearly is one: editing `package.json` `contributes` / `activationEvents` / `keybindings`, an `activate(context)` function, importing from `vscode`, leaking disposables, `yo code`, `vsce`, `.vscodeignore`, bundling with esbuild, publishing to the Marketplace or Open VSX, Webview CSP/nonce/postMessage, or testing with @vscode/test-electron. Not for: configuring your own editor, Claude Code plugins or MCP servers, or general TypeScript/Node questions with no extension host involved.'
+description: 'VS Code extension development grounded in the official Extension API docs. Use this whenever someone is creating, scaffolding, designing, debugging, testing, bundling or publishing a VS Code extension — TreeView, QuickPick, Webview, StatusBar, commands, configuration, SecretStorage, progress indicators, FileSystemWatcher, Diagnostics, Language Server Protocol, Debug Adapter Protocol, notebooks — and also when they never say "extension" but the work clearly is one: editing `package.json` `contributes` / `activationEvents` / `keybindings`, an `activate(context)` function, importing from `vscode`, leaking disposables, `yo code`, `vsce`, `.vscodeignore`, bundling with esbuild or webpack, publishing to the Marketplace or Open VSX, Webview CSP/nonce/postMessage, or testing with @vscode/test-electron. Not for: configuring your own editor (user settings, keybindings, installing extensions), Claude Code plugins, skills or MCP servers, or general TypeScript/Node questions with no extension host involved.'
 ---
 
 # VS Code Extension Development Skill
@@ -32,10 +32,12 @@ The SKILL.md alone is an **index** of references. The detail you need to give ac
 
 ### Step 2 — Output contract
 
-Every API symbol, configuration key, command, or behavior you cite MUST be backed by a citation in the form:
+Every API symbol, configuration key, command, or 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: *"Push all subscriptions to `context.subscriptions` so they are disposed on deactivation [source: references/api-additional.md]"*
 
 ### Step 3 — If you must answer from memory