@maccesar/aiskills 1.21.1 → 1.22.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.
 
 ---
 
@@ -73,6 +73,7 @@ All three platforms use the same Agent Skills format: a `SKILL.md` file with YAM
 | 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         |
+| 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         |
 
@@ -80,20 +81,22 @@ Use `aiskills list` to see available skills from the command line. Pull requests
 
 ---
 
-## Available commands
+## Explicit-only release skill
 
-Slash commands are Claude Code-only. They ship with the plugin (Option A). The CLI distribution (Option B) installs skills only.
+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.
 
-| Command    | Purpose                                                                        |
-| ---------- | ------------------------------------------------------------------------------ |
-| `/release` | Full release workflow: detect project, bump semver, update CHANGELOG + README, commit, push, tag, GitHub release |
+Unlike the other skills, `release` is never supposed to activate merely because a repository looks ready. Name it explicitly:
 
-### /release
+| 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]` |
 
-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.
+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 +104,8 @@ Example prompts:
 ```
 /release
 /release minor
-/release major
+$release major
+Use the release skill with a patch bump
 ```
 
 How it works:
@@ -128,15 +132,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 +151,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.
 
 ---
 

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,6 +31,7 @@ export const SKILLS = [
   'humaniza',
   'npm-supply-chain',
   'refactoring-ui',
+  'release',
   'seo-launch',
   'session-log',
   'stitch-showcase',
@@ -41,12 +42,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.22.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.