@maccesar/aiskills 1.21.1 → 1.23.0

package/README.md

@@ -8,7 +8,7 @@
 
 `aiskills` is a toolkit of curated skills for AI coding assistants. It provides skill files for Claude Code, Gemini CLI, or Codex CLI.
 
-Each skill is a small knowledge package: a `SKILL.md` file with YAML frontmatter plus a set of reference files. When a prompt matches the skill, the assistant reads those files and answers from the source material.
+Each skill is a small knowledge package: a `SKILL.md` file with YAML frontmatter plus optional references, scripts, and invocation policy. Most activate when a prompt matches; sensitive workflows such as `release` can require explicit invocation.
 
 ---
 
@@ -42,20 +42,20 @@ Installed files:
 
 ### Which option should I use?
 
-| | Plugin (Option A) | CLI (Option B) |
-|---|---|---|
-| **Claude Code** | Recommended | Supported |
-| **Gemini CLI** | Not available | Supported |
-| **Codex CLI** | Not available | Supported |
-| **Auto-updates** | Via marketplace | `aiskills update` |
+|                  | Plugin (Option A) | CLI (Option B)    |
+| ---------------- | ----------------- | ----------------- |
+| **Claude Code**  | Recommended       | Supported         |
+| **Gemini CLI**   | Not available     | Supported         |
+| **Codex CLI**    | Not available     | Supported         |
+| **Auto-updates** | Via marketplace   | `aiskills update` |
 
 ---
 
 ## Compatible platforms
 
-| Platform                                                  | Status    | Installation Path   |
-| --------------------------------------------------------- | --------- | ------------------- |
-| [Claude Code](https://claude.ai/claude-code)              | Supported | `~/.claude/skills/` |
+| Platform                                                  | Status    | Installation Path                     |
+| --------------------------------------------------------- | --------- | ------------------------------------- |
+| [Claude Code](https://claude.ai/claude-code)              | Supported | `~/.claude/skills/`                   |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Supported | `~/.agents/skills/` (auto-discovered) |
 | [Codex CLI](https://developers.openai.com/codex/cli/)     | Supported | `~/.agents/skills/` (auto-discovered) |
 
@@ -65,35 +65,47 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 
 ## Available skills
 
-| Skill                | Domain       | Source                               | Reference Files |
-| -------------------- | ------------ | ------------------------------------ | --------------- |
-| refactoring-ui       | Design       | "Refactoring UI" by Wathan & Schoger | 7 files         |
-| humaniza             | Writing (es) | Curated Spanish/es-MX style rules    | 7 files         |
-| audit-codebase       | Auditing     | Evidence-based audit methodology     | 2 files         |
-| vscode-extension-dev | VS Code      | VS Code Extension API docs           | 14 files        |
-| 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         |
+| Skill                 | Domain           | Source                                | Reference Files      |
+| --------------------- | ---------------- | ------------------------------------- | -------------------- |
+| refactoring-ui        | Design           | "Refactoring UI" by Wathan & Schoger  | 7 files              |
+| humaniza              | Writing (es)     | Curated Spanish/es-MX style rules     | 7 files              |
+| audit-codebase        | Auditing         | Evidence-based audit methodology      | 2 files              |
+| vscode-extension-dev  | VS Code          | VS Code Extension API docs            | 14 files             |
+| stitch-showcase       | Design Tools     | Google Stitch export workflow         | 16 files             |
+| session-log           | Project          | Convention + 3 A/B rounds             | 2 files              |
+| technical-demo-videos | Video Production | Reproducible macOS technical demos    | 9 guides + 4 scripts |
+| release               | Publishing       | Portable, confirmation-gated workflow | 1 file               |
+| 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.
 
----
+### Technical demo videos
+
+`technical-demo-videos` turns a conversational tutorial idea and a project path into a reviewable storyboard, a permanent recorder, an event log, narration and caption sources, and a verified delivery master. It loads the appropriate framework or domain skills before writing technical claims, prepares VS Code outside the capture, announces every real recording with a clapperboard, uses a fresh disposable project for each take, and keeps all production sources needed to recreate the result. YouTube upload automation and vertical derivatives remain opt-in.
 
-## Available commands
+Automated YouTube publication requires an explicit channel and playlist choice (including an explicit no-playlist choice), validates both against the authenticated account, and binds execution to a reviewed dry run with a confirmation token.
 
-Slash commands are Claude Code-only. They ship with the plugin (Option A). The CLI distribution (Option B) installs skills only.
+The workstation geometry and temporary-copy directory are configuration, not assumptions baked into the skill. A team can calibrate one profile and reuse the same workflow for a CLI, web app, mobile simulator, build process, or another technical tutorial.
 
-| Command    | Purpose                                                                        |
-| ---------- | ------------------------------------------------------------------------------ |
-| `/release` | Full release workflow: detect project, bump semver, update CHANGELOG + README, commit, push, tag, GitHub release |
+---
 
-### /release
+## Explicit-only release skill
 
 End-to-end release janitor that works across project types: npm, Titanium (`tiapp.xml`), Composer, Cargo, CocoaPods, or versionless (git-tag-only) repos. **Designed for a dirty working tree** — it groups your uncommitted work into semantic commits, then ships the release on top.
 
+Unlike the other skills, `release` is never supposed to activate merely because a repository looks ready. Name it explicitly:
+
+| Platform    | Invocation                                                |
+| ----------- | --------------------------------------------------------- |
+| Claude Code | `/release [patch\|minor\|major]`                          |
+| Codex CLI   | `$release [patch\|minor\|major]`                          |
+| Gemini CLI  | `Use the release skill [with a patch\|minor\|major bump]` |
+
+Codex carries platform-specific metadata that disables implicit invocation. Claude Code has its own equivalent frontmatter field, but adding it to this universal `SKILL.md` makes Codex reject the skill; the common body therefore enforces the boundary for Claude and Gemini: the prompt must name `release` before the workflow may proceed. Gemini still asks for activation consent. Every platform then stops again at the release plan and requires a second explicit confirmation before any mutation.
+
 When to use it:
-- You have weeks of work in the working tree (with maybe a few interim commits you made along the way) and want one command to clean everything into proper semantic commits and ship a release.
+- You have weeks of work in the working tree (with maybe a few interim commits you made along the way) and want one workflow to clean everything into proper semantic commits and ship a release.
 - You maintain `CHANGELOG.md` in Keep-a-Changelog format and want the `[Unreleased]` section promoted automatically.
 - You want the bump level inferred from Conventional Commits across both your existing commits and the proposed new ones, with the option to override.
 
@@ -101,7 +113,8 @@ Example prompts:
 ```
 /release
 /release minor
-/release major
+$release major
+Use the release skill with a patch bump
 ```
 
 How it works:
@@ -128,15 +141,16 @@ Language policy (two independent axes):
 Hard restrictions:
 - Never `--force-push`, `--amend` published commits, or `--no-verify`.
 - Aborts on merge conflicts or rebase-in-progress.
-- Asks before creating the **first** tag on `main` / `master`.
+- Warns before creating the first tag or GitHub release in a public/internal repository.
 - Skips push / tag / release gracefully when the repo has no remote or `gh` is not installed.
 
 Distribution note:
-- Available via the plugin install (Option A above). Slash commands are not distributed by the npm CLI (Option B) because they are a Claude Code feature.
+- The release workflow now ships through both installation options as one Agent Skill. The former Claude-only `commands/release.md` is removed automatically on the next `aiskills update` or `aiskills install`.
+- If npm updates before an enabled Claude marketplace cache, the CLI keeps the old plugin command as the temporary `/release` provider and suppresses the new same-name mirror rather than creating a duplicate. Refresh with `/plugin marketplace update maccesar-aiskills`, run `aiskills install`, then `/reload-plugins` to finish the handoff to the skill.
 
 ## How skills work
 
-Skills activate based on what you ask. You can write prompts normally:
+Most skills activate based on what you ask. You can write prompts normally:
 
 ```
 "How do I create better visual hierarchy in this UI?"
@@ -146,7 +160,7 @@ Skills activate based on what you ask. You can write prompts normally:
 
 The assistant reads the skill's `SKILL.md`, checks whether the request fits, and then loads the reference files for that skill. That keeps the answer tied to the source material.
 
-You do not need to name a skill explicitly, though you still can if you want to force a specific one.
+You do not normally need to name a skill explicitly. `release` is the deliberate exception because it can commit, tag, push, and publish; invoke it using the platform-specific form documented above.
 
 ---
 
@@ -177,15 +191,15 @@ Example prompts:
 ```
 
 Reference files:
-| File                     | Topics                                                                                  |
-| ------------------------ | --------------------------------------------------------------------------------------- |
+| File                     | Topics                                                                                   |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
 | 01-foundations.md        | Project mindset: feature-first work, scope discipline, defining systems, picking a voice |
-| 02-page-mechanics.md     | Visual hierarchy, layout, white space, spacing scales, typography                       |
-| 03-visual-treatment.md   | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling         |
-| 04-polish.md             | Borders, accents, empty states, decorative defaults, sharpening design intuition        |
-| 05-motion.md             | Motion system, hover/press states, loading patterns, `prefers-reduced-motion`           |
-| 06-dark-mode.md          | Dark mode color tokens, text contrast, shadows, images, theme toggle                    |
-| 07-component-patterns.md | Modals (focus, layout), forms (labels, validation), tables (density, alignment)         |
+| 02-page-mechanics.md     | Visual hierarchy, layout, white space, spacing scales, typography                        |
+| 03-visual-treatment.md   | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling          |
+| 04-polish.md             | Borders, accents, empty states, decorative defaults, sharpening design intuition         |
+| 05-motion.md             | Motion system, hover/press states, loading patterns, `prefers-reduced-motion`            |
+| 06-dark-mode.md          | Dark mode color tokens, text contrast, shadows, images, theme toggle                     |
+| 07-component-patterns.md | Modals (focus, layout), forms (labels, validation), tables (density, alignment)          |
 
 ---
 
@@ -258,7 +272,7 @@ Example prompts:
 ```
 
 Reference files:
-| File                   | Topics                                                                     |
+| File                   | Topics                                                                      |
 | ---------------------- | --------------------------------------------------------------------------- |
 | comprehensive-audit.md | Mandatory principles, 24-area technical scope, 5-phase method, severity     |
 | report-format.md       | Executive summary, findings table, decision matrix, correction plan formats |
@@ -297,22 +311,22 @@ Example prompts:
 ```
 
 Reference files:
-| File                   | Topics                                                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
-| api-treeview.md        | TreeDataProvider, TreeView registration                                                                    |
-| api-webview.md         | Webview Panel, CSP/nonce, postMessage, asWebviewUri                                                        |
-| api-quickpick.md       | Simple and async QuickPick with debounced search                                                           |
-| api-statusbar.md       | StatusBarItem, codicons, dynamic updates                                                                   |
-| api-secretstorage.md   | Credential manager pattern, onDidChange                                                                    |
-| api-progress.md        | withProgress (Notification + Window), cancellation tokens                                                  |
+| File                   | Topics                                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
+| api-treeview.md        | TreeDataProvider, TreeView registration                                                                     |
+| api-webview.md         | Webview Panel, CSP/nonce, postMessage, asWebviewUri                                                         |
+| api-quickpick.md       | Simple and async QuickPick with debounced search                                                            |
+| api-statusbar.md       | StatusBarItem, codicons, dynamic updates                                                                    |
+| api-secretstorage.md   | Credential manager pattern, onDidChange                                                                     |
+| api-progress.md        | withProgress (Notification + Window), cancellation tokens                                                   |
 | api-additional.md      | FileSystemWatcher, Disposable cleanup, Diagnostics, OutputChannel, ContextKeys, TextDocumentContentProvider |
-| architecture.md        | Project structure, layered architecture, testing strategy                                                  |
-| package-json-schema.md | contributes, activationEvents, engines, scripts, devDependencies                                           |
-| publishing.md          | vsce, .vscodeignore, CI/CD, Open VSX, versioning                                                           |
-| lsp.md                 | LSP client setup, server lifecycle, capabilities, diagnostics                                              |
-| notebooks.md           | Notebook serializers, controllers, renderers, output mime types                                            |
-| debugger.md            | DAP: descriptor factory, configuration provider, adapter lifecycle                                         |
-| testing.md             | Multi-suite test config, workspace fixtures, mocking `vscode`, CI, coverage                                |
+| architecture.md        | Project structure, layered architecture, testing strategy                                                   |
+| package-json-schema.md | contributes, activationEvents, engines, scripts, devDependencies                                            |
+| publishing.md          | vsce, .vscodeignore, CI/CD, Open VSX, versioning                                                            |
+| lsp.md                 | LSP client setup, server lifecycle, capabilities, diagnostics                                               |
+| notebooks.md           | Notebook serializers, controllers, renderers, output mime types                                             |
+| debugger.md            | DAP: descriptor factory, configuration provider, adapter lifecycle                                          |
+| testing.md             | Multi-suite test config, workspace fixtures, mocking `vscode`, CI, coverage                                 |
 
 ---
 
@@ -322,12 +336,12 @@ Gives a project one predictable place for its working state, so both you and any
 
 The convention:
 
-| File | Holds | Loaded at startup |
-| --- | --- | --- |
-| `status.md` | Where the work stands: half-done things, next step, what's blocked, deployment state, which assistant wrote the note | **No** |
-| `requirements.md` | What the system must do, and the acceptance criterion for each item | Yes |
-| `decisions.md` | What was chosen and why. Append-only, dated | Yes |
-| `context.md` | Documentation map, architecture, conventions, traps, provenance | Yes |
+| File              | Holds                                                                                                                | Loaded at startup |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `status.md`       | Where the work stands: half-done things, next step, what's blocked, deployment state, which assistant wrote the note | **No**            |
+| `requirements.md` | What the system must do, and the acceptance criterion for each item                                                  | Yes               |
+| `decisions.md`    | What was chosen and why. Append-only, dated                                                                          | Yes               |
+| `context.md`      | Documentation map, architecture, conventions, traps, provenance                                                      | Yes               |
 
 **Why `status.md` is excluded from startup.** Cached context is matched as a prefix — the first byte that differs invalidates everything after it. Status written inside a startup-loaded file means every update throws away the cache for all the stable content behind it. The file you edit most often is the one that must not load at startup.
 
@@ -357,10 +371,10 @@ What it will not do:
 
 Measured behaviour, across three A/B rounds against a no-skill baseline (18 runs, adversarially graded):
 
-| | With skill | Without |
-| --- | --- | --- |
-| Kept volatile status out of the startup chain | 9 / 9 | 0 / 9 |
-| Left the user's broken uncommitted code untouched | yes | no — fixed it unasked |
+|                                                   | With skill | Without               |
+| ------------------------------------------------- | ---------- | --------------------- |
+| Kept volatile status out of the startup chain     | 9 / 9      | 0 / 9                 |
+| Left the user's broken uncommitted code untouched | yes        | no — fixed it unasked |
 
 Token cost is 3–13% higher per run. **Those rounds graded an earlier layout** — a single status file versus an imported memory index — so what they establish is the split itself, not the four filenames. The paths added since (resuming against a stale file, upgrading an earlier install, monorepos, a gitignored `docs/`) have prompts written for them and have not been run. The grading notes, and an explicit account of what is and isn't measured, are in `skills/session-log/evals/`.
 
@@ -475,13 +489,13 @@ Certificate verification is on by default; `--local` is the explicit opt-out for
 
 **Stage 2**, once you approve, installs the tags from a parameterized template, generates the images with ImageMagick, writes `robots.txt` / `sitemap.xml` / `.htaccess`, and re-runs the audit against the live site to verify.
 
-| Reference file | Covers |
-| --- | --- |
-| `head-tags.md` | title, description, canonical, robots, the Open Graph block, Twitter card, and why the URLs must be absolute |
-| `images.md` | og:image 1200×630, SVG favicon, apple-touch-icon, and the ImageMagick commands with the decision behind each flag |
-| `server-files.md` | robots.txt, sitemap.xml, .htaccess: canonical domain, compression, split caching, security headers |
-| `structured-data.md` | JSON-LD for LocalBusiness, Organization, Article and BreadcrumbList |
-| `search-engines.md` | Search Console (Domain vs URL prefix), Bing, submitting the sitemap, validators, busting Facebook's cache |
+| Reference file       | Covers                                                                                                            |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `head-tags.md`       | title, description, canonical, robots, the Open Graph block, Twitter card, and why the URLs must be absolute      |
+| `images.md`          | og:image 1200×630, SVG favicon, apple-touch-icon, and the ImageMagick commands with the decision behind each flag |
+| `server-files.md`    | robots.txt, sitemap.xml, .htaccess: canonical domain, compression, split caching, security headers                |
+| `structured-data.md` | JSON-LD for LocalBusiness, Organization, Article and BreadcrumbList                                               |
+| `search-engines.md`  | Search Console (Domain vs URL prefix), Bing, submitting the sitemap, validators, busting Facebook's cache         |
 
 Templates in `assets/`: a parameterized `head.php` for static sites, a `social-meta.blade.php` component for Laravel, a commented `.htaccess`, and a `robots.txt`.
 
@@ -516,13 +530,13 @@ It reports tokens sitting in `~/.npmrc` or the project `.npmrc`, Actions secrets
 
 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 |
+| 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 |
+| `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.
 
@@ -583,9 +597,9 @@ aiskills auto-update --silent   # No output (for hooks)
 ```
 
 Options:
-| Option        | Description                          |
-| ------------- | ------------------------------------ |
-| `-s, --silent` | Suppress all output except errors   |
+| Option         | Description                       |
+| -------------- | --------------------------------- |
+| `-s, --silent` | Suppress all output except errors |
 
 What it does:
 1. Checks a local cache (`~/.aiskills/last-check.json`) — if already checked today, exits immediately

package/lib/commands/doctor.js

@@ -75,7 +75,9 @@ export async function doctorCommand() {
     }
   }
   const expectedCommands = COMMANDS.length - pluginCommands.length;
-  if (pluginCommands.length === COMMANDS.length) {
+  if (COMMANDS.length === 0) {
+    console.log(`  ${CHECK} Slash commands: none (workflows ship as cross-agent skills)`);
+  } else if (pluginCommands.length === COMMANDS.length) {
     console.log(`  ${CHECK} Slash commands: all ${COMMANDS.length} served by the marketplace plugin`);
   } else if (missingCommands.length === 0) {
     console.log(`  ${CHECK} Slash commands: ${expectedCommands}/${expectedCommands} installed in ~/.claude/commands/`);
@@ -113,10 +115,13 @@ export async function doctorCommand() {
 
     for (const skill of SKILLS) {
       // A skill the marketplace plugin provides is *supposed* to have no mirror
-      // here — the CLI removes it on purpose to avoid a duplicate entry. Counting
-      // it as missing turns a healthy marketplace install into a wall of errors
-      // telling the user to run a command that will correctly do nothing.
-      if (platform.name === 'claude' && pluginProvidesSkill(skill, homeDir)) {
+      // here — the CLI removes it on purpose to avoid a duplicate entry. During
+      // command-to-skill migrations, a same-name command in an older enabled
+      // cache also suppresses the mirror until the marketplace refreshes.
+      if (
+        platform.name === 'claude' &&
+        (pluginProvidesSkill(skill, homeDir) || pluginProvidesCommand(skill, homeDir))
+      ) {
         servedByPlugin.push(skill);
         continue;
       }

package/lib/config.js

@@ -31,9 +31,11 @@ export const SKILLS = [
   'humaniza',
   'npm-supply-chain',
   'refactoring-ui',
+  'release',
   'seo-launch',
   'session-log',
   'stitch-showcase',
+  'technical-demo-videos',
   'vscode-extension-dev',
 ];
 
@@ -41,12 +43,10 @@ export const SKILLS = [
 export const LEGACY_SKILLS = [];
 
 // Slash commands to install (Claude Code only — copied to ~/.claude/commands/)
-export const COMMANDS = [
-  'release',
-];
+export const COMMANDS = [];
 
 // Legacy commands to remove during updates/uninstall
-export const LEGACY_COMMANDS = [];
+export const LEGACY_COMMANDS = ['release'];
 
 // Cache/config directory
 export const getConfigDir = () => path.join(os.homedir(), '.aiskills');

package/lib/symlink.js

@@ -83,8 +83,8 @@ async function removePath(path) {
  * @returns {Promise<boolean>} True if the plugin provides this skill
  */
 export async function isClaudePluginSkillInstalled(skillName, baseDir) {
-  const { pluginProvidesSkill } = await import('./claude-plugin.js');
-  return pluginProvidesSkill(skillName, baseDir);
+  const { pluginProvidesSkill, pluginProvidesCommand } = await import('./claude-plugin.js');
+  return pluginProvidesSkill(skillName, baseDir) || pluginProvidesCommand(skillName, baseDir);
 }
 
 /**
@@ -118,8 +118,9 @@ export async function createSkillSymlinks(platformSkillsDir, skills, baseDir) {
   const useRelative = !!baseDir;
 
   for (const skill of skills) {
-    // Skip Claude when the marketplace plugin already provides this skill;
-    // clean up any stale symlink left from a previous CLI install.
+    // Skip Claude when the marketplace plugin already provides this skill or
+    // still provides a same-name legacy command during a command-to-skill
+    // migration; clean up any stale symlink left from a previous CLI install.
     if (isClaudePlatform && await isClaudePluginSkillInstalled(skill, baseDir)) {
       const stalePath = join(platformSkillsDir, skill);
       if (existsSync(stalePath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.21.1",
+  "version": "1.23.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "codex",
     "llm",
     "agents",
+    "release",
     "refactoring-ui",
     "design",
     "ui",

package/skills/release/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: release
+description: 'Use only when the user explicitly invokes `$release`, `/release`, or asks to use the release skill by name. Never activate merely because work appears ready or the user discusses releases. Handles the full repository release workflow: semantic commits, semver, CHANGELOG and README updates, confirmation, push, tag, GitHub release, and publication verification.'
+---
+
+# Release
+
+Publish a repository only through an explicit, reviewable authorization sequence.
+
+## Invocation boundary
+
+This is an explicit-only skill.
+
+- Proceed only when the user's current request names `$release`, `/release`, or the `release` skill itself.
+- A generic request that merely discusses releases, versions, tags, publishing, or a repository that looks ready is not an invocation. Stop and tell the user how to invoke the skill.
+- Invoking the skill authorizes read-only analysis and a release plan. It does not authorize commits, tags, pushes, package publication, GitHub releases, merges, or pull requests.
+- Accept an optional `patch`, `minor`, or `major` override from the invocation. Otherwise infer the bump from the repository changes.
+
+## Required workflow
+
+1. Read [references/workflow.md](references/workflow.md) completely before running repository checks.
+2. Follow its Steps 0–4 in order and present the single confirmation block.
+3. Stop. Do not perform any mutation until the user explicitly confirms that exact plan.
+4. After confirmation, follow Step 5 exactly and verify every publication channel triggered by the release.
+
+Repository instructions remain authoritative. If they impose stricter release checks or extra synchronized version files, include those requirements in the plan and execution.

package/skills/release/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Release"
+  short_description: "Plan, confirm, and publish a repository release"
+  default_prompt: "Use $release to prepare and publish this repository after showing me the confirmation plan."
+policy:
+  allow_implicit_invocation: false

package/{commands/release.md → skills/release/references/workflow.md}

@@ -1,39 +1,46 @@
----
-allowed-tools: Bash(git:*), Bash(gh:*), Bash(npm version:*), Bash(npm pkg:*), Bash(cat:*), Bash(grep:*), Bash(test:*), Read, Edit, Write, Glob, Grep
-description: Full release workflow — detect project, infer semver bump, update CHANGELOG+README, commit, push. Public repos get a tag + GitHub release (asks before the first ever tag or release); private repos skip both by default.
-argument-hint: [patch|minor|major] (optional; inferred from semantic commits if omitted)
----
-
-## Context (read-only — collected automatically)
-
-- Working tree status: !`git status --porcelain`
-- Current branch: !`git branch --show-current`
-- Last tag: !`git describe --tags --abbrev=0 2>/dev/null || echo "<no tags>"`
-- Commits since last tag: !`git log --pretty=format:"%h %s" $(git describe --tags --abbrev=0 2>/dev/null)..HEAD 2>/dev/null || git log --pretty=format:"%h %s"`
-- Remote URL: !`git remote get-url origin 2>/dev/null || echo "<no remote>"`
-- Recent commit style: !`git log --pretty=format:"%s" -20`
-- Has gh CLI: !`command -v gh >/dev/null 2>&1 && echo "yes" || echo "no"`
-- Repo visibility (GitHub only): !`gh repo view --json visibility -q .visibility 2>/dev/null || echo "<unknown>"`
-- Versioned files present:
-  - package.json: !`test -f package.json && echo "yes" || echo "no"`
-  - tiapp.xml: !`test -f tiapp.xml && echo "yes" || echo "no"`
-  - composer.json: !`test -f composer.json && echo "yes" || echo "no"`
-  - Cargo.toml: !`test -f Cargo.toml && echo "yes" || echo "no"`
-  - podspec: !`ls *.podspec 2>/dev/null | head -1 || echo "<none>"`
-- CHANGELOG.md present: !`test -f CHANGELOG.md && echo "yes" || echo "no"`
-- README.md present: !`test -f README.md && echo "yes" || echo "no"`
-
-## Arguments
-
-`$ARGUMENTS` may contain `patch`, `minor`, or `major` to override the inferred bump. If empty, infer from the commits above.
+# Release workflow
+
+<!-- TOC-START -->
+## Contents
+
+- [Read-only context to collect](#read-only-context-to-collect)
+- [Your task](#your-task)
+  - [What this skill actually does (read this first)](#what-this-skill-actually-does-read-this-first)
+  - [Verbosity discipline](#verbosity-discipline)
+  - [Step 0 — Lock interaction language (do this BEFORE printing anything)](#step-0--lock-interaction-language-do-this-before-printing-anything)
+  - [Step 1 — Establish state (silent)](#step-1--establish-state-silent)
+  - [Step 2 — Infer the bump (silent)](#step-2--infer-the-bump-silent)
+  - [Step 3 — Compose the CHANGELOG entry (silent)](#step-3--compose-the-changelog-entry-silent)
+  - [Language policy (applies to Steps 1–5)](#language-policy-applies-to-steps-15)
+  - [Step 4 — Present the plan in ONE block and STOP](#step-4--present-the-plan-in-one-block-and-stop)
+  - [Step 5 — Execute (silent until done)](#step-5--execute-silent-until-done)
+- [Hard restrictions (never violate)](#hard-restrictions-never-violate)
+
+<!-- TOC-END -->
+
+## Read-only context to collect
+
+Collect this state with read-only tools before planning anything:
+
+- Working tree status: `git status --porcelain`
+- Current branch: `git branch --show-current`
+- Last tag: `git describe --tags --abbrev=0`
+- Commits since the last tag, or the full log when no tag exists
+- Remote URL and primary branch
+- Recent commit subjects and conventions
+- Whether `gh` is installed and, for GitHub remotes, repository visibility
+- Presence of `package.json`, `tiapp.xml`, `composer.json`, `Cargo.toml`, a root `*.podspec`, `CHANGELOG.md`, and `README.md`
+- Merge or rebase state and unresolved conflicts
+
+The explicit invocation may include `patch`, `minor`, or `major` to override the inferred bump. If none is present, infer it from the work being released.
 
 ## Your task
 
 Execute the **release workflow** in five strict, ordered steps. **Do not skip Step 4** — it is the user's confirmation gate and is non-negotiable.
 
-### What this command actually does (read this first)
+### What this skill actually does (read this first)
 
-`/release` is **not** "make a release commit from already-staged work". It is the full janitor: it takes a project that has been worked on without commits (or with mixed work + a release intent) and turns it into a clean, shipped release.
+The release skill is **not** "make a release commit from already-staged work". It is the full janitor: it takes a project that has been worked on without commits (or with mixed work + a release intent) and turns it into a clean, shipped release.
 
 **Working tree dirty is the expected starting state, not an anomaly.** When the user invokes `/release` with 12 modified files since the last tag, what they want is:
 
@@ -55,9 +62,9 @@ If the working tree is **completely empty** AND there are zero commits since the
 
 ### Step 0 — Lock interaction language (do this BEFORE printing anything)
 
-Before you produce any user-facing output, scan the user's last 1–3 messages in this conversation and determine their language. **This file is in English for distribution; that does not mean you respond in English.** Lock that detected language and use it for **every** message you print to the user from this point until the command ends — Step 1 summary, Step 2 inferred bump, Step 4 plan preview, Step 5 progress, errors, final report.
+Before you produce any user-facing output, scan the user's last 1–3 messages in this conversation and determine their language. **This file is in English for distribution; that does not mean you respond in English.** Lock that detected language and use it for every message you print to the user until the skill ends: the Step 4 plan, errors, and final report.
 
-If the user has not yet said anything in this session (rare — `/release` invoked as the very first message), default to the language of the repo's `README.md`. If that is also unclear, default to English.
+If the user has not yet said anything in this session (rare when the skill is invoked as the first message), default to the language of the repo's `README.md`. If that is also unclear, default to English.
 
 If the user switches language mid-flow, switch with them on the next message.
 
@@ -168,7 +175,7 @@ Apply Conventional Commits rules across that combined set:
 - Any `feat:` (no breaking) → **minor**
 - Otherwise → **patch**
 
-`$ARGUMENTS` (`patch` / `minor` / `major`) overrides the inference.
+An explicit invocation override (`patch` / `minor` / `major`) takes precedence over the inference.
 
 If there are zero existing commits AND zero proposed commits AND the working tree is clean → abort: "Nothing to release."
 
@@ -208,7 +215,7 @@ There are **two independent language axes**. Do not mix them.
 
 #### Axis 1 — Interaction language (your conversation with the user)
 
-**Always match the user's language.** Detect from the user's last 1–3 messages in this conversation — not from this command file (which is in English for distribution), and not from the project files. If the user has been speaking Spanish, every status summary, plan preview, confirmation prompt, error message, and final report you print **must be in Spanish**. If the user switches mid-flow, switch with them.
+**Always match the user's language.** Detect from the user's last 1–3 messages in this conversation — not from this workflow file (which is in English for distribution), and not from the project files. If the user has been speaking Spanish, every plan preview, confirmation prompt, error message, and final report you print **must be in Spanish**. If the user switches mid-flow, switch with them.
 
 This is about what the user **reads on screen**. It does **not** affect what gets written to disk or to GitHub.
 
@@ -222,7 +229,7 @@ This is about what the user **reads on screen**. It does **not** affect what get
 2. Classify the prose: Spanish, English, or other.
 3. Tie-break with `CHANGELOG.md` (recent entries) if README is too short or ambiguous.
 4. Final tie-break: the recent `git log` subjects.
-5. If everything is ambiguous, default to English and tell the user in the Step 1 summary so they can correct you before Step 4.
+5. If everything is ambiguous, default to English and surface that assumption in the Step 4 block so the user can correct it before confirming.
 
 The detected language applies to **all** of the following:
 
@@ -284,7 +291,7 @@ CHANGELOG entry:
 ### Fixed
 - ...
 
-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
+README updates (gaps found): <one-line per gap, e.g. "add the new public skill to the available-skills table">  ← omit this line if no gaps
 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
@@ -427,9 +434,9 @@ If everything was routine and no merge was requested, the second line is just th
 - **Never** `--no-verify`, `--no-gpg-sign`, or any hook-skipping flag unless the user explicitly asks.
 - **Never** delete tags or branches.
 - **Never** merge to main with anything other than `--ff-only`. If fast-forward is not possible, abort and let the user resolve. Do not fall back to `--no-ff`, `-X theirs`, `-X ours`, or any rebase strategy.
-- **Never** proceed past Step 4 without explicit confirmation. The slash command itself is consent to **invoke**, not consent to commit and push.
+- **Never** proceed past Step 4 without explicit confirmation. Explicitly invoking the skill is consent to **plan**, not consent to commit and push.
 - If the working tree has merge conflicts or rebase-in-progress markers → **abort** with a diagnosis and let the user resolve manually.
 - If the repo is **public/internal** and has **no prior tag** and/or **no prior GitHub release**, surface a ⚠️ line in the Step 4 plan (one per missing milestone) before creating the first ever tag or release — these are meaningful one-way actions. The user's plain confirmation in Step 4 (`yes` / `sí` / `proceed` / …) covers both ⚠️s in that single round-trip; do not require a separate confirmation prompt. On a **private repo** these confirmations are unnecessary and must NOT be raised — private mode skips both the tag and the GitHub release by default, so there's nothing to confirm. The user already opted in/out via the `con tag` modifier in Step 4 (and even then, the GitHub release stays skipped on private repos).
-- If the repo has no remote → run Steps 5.1–5.5 only; skip push, tag, and release. Tell the user.
-- If the repo has a remote but `gh` is not available → run through 5.7's tag step but skip the GitHub release; tell the user how to create the release manually if they want to.
+- If the repo has no remote → land the semantic and release commits only; skip push, tag, and GitHub release. Tell the user.
+- If the repo has a remote but `gh` is not available → push the branch and tag, but skip the GitHub release; tell the user how to create it manually if they want to.
 - **Never** create a GitHub release on a private repo, even if the user added `con tag` to the confirmation. The `con tag` modifier only re-enables the git tag; the GitHub release stays skipped.