agentic-awesome-skills 14.2.0 → 14.3.0

package/README.md

@@ -1,9 +1,9 @@
-<!-- registry-sync: version=14.2.0; skills=1946; stars=42926; updated_at=2026-07-12T05:22:55+00:00 -->
+<!-- registry-sync: version=14.3.0; skills=1948; stars=43042; updated_at=2026-07-13T07:58:11+00:00 -->
 [![Agentic Awesome Skills social preview](apps/web-app/public/social-card.png)](https://github.com/sickn33/agentic-awesome-skills)
 
-# 🌌 Agentic Awesome Skills: 1,946+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Autohand Code, Copilot & More
+# 🌌 Agentic Awesome Skills: 1,948+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Autohand Code, Copilot & More
 
-> **Installable GitHub library of 1,946+ agentic skills for Claude Code, Cursor, Codex CLI, Autohand Code, Gemini CLI, Antigravity, and other AI coding assistants.**
+> **Installable GitHub library of 1,948+ agentic skills for Claude Code, Cursor, Codex CLI, Autohand Code, Gemini CLI, Antigravity, and other AI coding assistants.**
 
 Agentic Awesome Skills is an installable GitHub library and npm installer for reusable `SKILL.md` playbooks. It is designed for Claude Code, Cursor, Codex CLI, Autohand Code, Gemini CLI, Antigravity, Kiro, OpenCode, GitHub Copilot, and other AI coding assistants that benefit from structured operating instructions. Instead of collecting one-off prompt snippets, this repository gives you a searchable, installable catalog of skills, bundles, workflows, plugin-safe distributions, and practical docs that help agents perform recurring tasks with better context, stronger constraints, and clearer outputs.
 
@@ -13,7 +13,7 @@ You can use this repo to install a broad multi-tool skill library, start from fo
 
 The canonical project page is the GitHub repository at <https://github.com/sickn33/agentic-awesome-skills>; the hosted catalog is a companion discovery surface for search, plugins, and skill detail pages.
 
-**Start here:** [Install in 1 minute](#installation) · [Recommended plugins](#recommended-specialized-plugins) · [Compare plugin packs](https://sickn33.github.io/agentic-awesome-skills/plugins) · [Choose your tool](#choose-your-tool) · [📚 Browse 1,946+ Skills](#browse-1946-skills) · [Bundles & workflows](#bundles--workflows) · [Support the project](#support-the-project)
+**Start here:** [Install in 1 minute](#installation) · [Recommended plugins](#recommended-specialized-plugins) · [Compare plugin packs](https://sickn33.github.io/agentic-awesome-skills/plugins) · [Choose your tool](#choose-your-tool) · [📚 Browse 1,948+ Skills](#browse-1948-skills) · [Bundles & workflows](#bundles--workflows) · [Support the project](#support-the-project)
 
 [![GitHub stars](https://img.shields.io/badge/⭐%2043%2C000%2B%20Stars-gold?style=for-the-badge)](https://github.com/sickn33/agentic-awesome-skills/stargazers)
 [![Follow @AASkills_ on X](https://img.shields.io/badge/Follow-%40AASkills__-black?style=for-the-badge&logo=x)](https://x.com/AASkills_)
@@ -30,13 +30,13 @@ The canonical project page is the GitHub repository at <https://github.com/sickn
 [![OpenCode](https://img.shields.io/badge/OpenCode-CLI-gray?style=for-the-badge)](https://github.com/opencode-ai/opencode)
 [![Antigravity](https://img.shields.io/badge/Antigravity-AI%20IDE-red?style=for-the-badge)](https://github.com/sickn33/agentic-awesome-skills)
 
-**Current release: V14.2.0.** Trusted by 43k+ GitHub stargazers, this repository combines official and community skill collections with bundles, workflows, installation paths, and docs that help you go from first install to daily use quickly.
+**Current release: V14.3.0.** Trusted by 43k+ GitHub stargazers, this repository combines official and community skill collections with bundles, workflows, installation paths, and docs that help you go from first install to daily use quickly.
 
 ## Why This Repo
 
 - **Installable, not just inspirational**: use `npx agentic-awesome-skills` to put skills where your tool expects them.
 - **Built for major agent workflows**: Claude Code, Cursor, Codex CLI, Autohand Code, Gemini CLI, Antigravity, Kiro, OpenCode, Copilot, and more.
-- **Broad coverage with real utility**: 1,946+ skills across development, testing, security, infrastructure, product, and marketing.
+- **Broad coverage with real utility**: 1,948+ skills across development, testing, security, infrastructure, product, and marketing.
 - **Focused by default**: specialized plugins help you start with the web, security, data, docs, DevOps, QA, OSS, or agent/MCP workflows you actually need.
 - **Useful whether you want breadth or curation**: install the full catalog, choose a specialized plugin, start with bundles, or compare alternatives before installing.
 
@@ -48,7 +48,7 @@ The canonical project page is the GitHub repository at <https://github.com/sickn
 - [Choose Your Tool](#choose-your-tool)
 - [Quick FAQ](#quick-faq)
 - [Bundles & Workflows](#bundles--workflows)
-- [Browse 1,946+ Skills](#browse-1946-skills)
+- [Browse 1,948+ Skills](#browse-1948-skills)
 - [Troubleshooting](#troubleshooting)
 - [Stable Skills Manifest v1](#stable-skills-manifest-v1)
 - [Support the Project](#support-the-project)
@@ -79,6 +79,18 @@ npx agentic-awesome-skills --agy
 
 The npm installer uses a shallow, release-pinned clone by default so first-run installs stay lighter than a full repository history checkout while matching the published npm package version. Use `--tag main` only when you intentionally want the current repository tip.
 
+### Focused single-skill install with GitHub CLI (preview)
+
+GitHub CLI can preview and install one exact skill for Copilot and other supported hosts. Use an exact `SKILL.md` path in this large, mirrored repository so the selected source is unambiguous and discovery stays fast:
+
+```bash
+gh skill preview sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md
+gh skill install sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md \
+  --agent github-copilot --scope user --pin v14.2.0
+```
+
+`gh skill` support is currently a GitHub CLI preview and may change. Install a focused skill or plugin surface for the job; do not use `--all` unless you intentionally want every discovered canonical and mirrored skill.
+
 ### Verify the install
 
 ```bash
@@ -142,7 +154,7 @@ Use the same repository, but install or invoke it in the way your host expects.
 | Antigravity CLI (`agy`) | `npx agentic-awesome-skills --agy`                        | `/brainstorming help me plan a feature`              |
 | Kiro CLI       | `npx agentic-awesome-skills --kiro`                                | `Use brainstorming to plan a feature`                |
 | Kiro IDE       | `npx agentic-awesome-skills --path ~/.kiro/skills`                 | `Use @brainstorming to plan a feature`               |
-| GitHub Copilot | _No installer — paste skills or rules manually_                       | `Ask Copilot to use brainstorming to plan a feature` |
+| GitHub Copilot | `gh skill install sickn33/agentic-awesome-skills skills/brainstorming/SKILL.md --agent github-copilot --scope user --pin v14.2.0` (preview) | `Ask Copilot to use brainstorming to plan a feature` |
 | OpenCode       | `npx agentic-awesome-skills --path .agents/skills --category development,backend --risk safe,none` | `opencode run @brainstorming help me plan a feature` |
 | AdaL CLI       | `npx agentic-awesome-skills --path .adal/skills`                   | `Use brainstorming to plan a feature`                |
 | Custom path    | `npx agentic-awesome-skills --path ./my-skills`                    | Depends on your tool                                   |
@@ -159,7 +171,7 @@ Use the table above for install targets. Use specialized plugins when you are ch
 
 ### What is Agentic Awesome Skills?
 
-**Agentic Awesome Skills** (Release 14.2.0) is a large, installable skill library for AI coding assistants. It packages 1,946+ reusable `SKILL.md` playbooks, specialized plugins, bundles, workflows, generated catalogs, and a CLI installer so Claude Code, Codex CLI, Autohand Code, Cursor, Gemini CLI, Antigravity, and similar tools can reuse proven operating instructions instead of one-off prompts.
+**Agentic Awesome Skills** (Release 14.3.0) is a large, installable skill library for AI coding assistants. It packages 1,948+ reusable `SKILL.md` playbooks, specialized plugins, bundles, workflows, generated catalogs, and a CLI installer so Claude Code, Codex CLI, Autohand Code, Cursor, Gemini CLI, Antigravity, and similar tools can reuse proven operating instructions instead of one-off prompts.
 
 ### How do I install it?
 
@@ -224,7 +236,15 @@ If Antigravity starts hitting context limits with too many active skills, the ac
 
 If you use OpenCode or another `.agents/skills` host, prefer a reduced install up front instead of copying the full library into a context-sensitive runtime. The installer now supports `--risk`, `--category`, and `--tags` so you can keep the installed set narrow.
 
-## Browse 1,946+ Skills
+For a reproducible exact set, pin the package and catalog release and preview the full per-target plan before writing:
+
+```bash
+npx agentic-awesome-skills@14.3.0 --codex --release 14.3.0 --skills frontend-design,game-development/2d-games --dry-run
+```
+
+Remove `--dry-run` only after reviewing the install, update, and removal plan. Unknown or ambiguous skill identifiers fail closed, and metadata filters combine with `--skills` using AND.
+
+## Browse 1,948+ Skills
 
 Use the root repo as a landing page, then jump into the deeper surface that matches your intent.
 
@@ -398,6 +418,7 @@ Key source families include:
 - **[adelaidasofia/ai-brain-starter](https://github.com/adelaidasofia/ai-brain-starter)**: Source for the `ingest-youtube` skill - YouTube transcript ingestion into markdown vaults with yt-dlp metadata, VTT cleanup, and capture-seed stubs (MIT).
 - **[JDDavenport/context-kit](https://github.com/JDDavenport/context-kit)**: Source reference for the `context-kit` skill - local-first Personal Context Artifact setup, installer review, and private context hygiene for Claude Code and adjacent agent workflows.
 - **[JularDepick/user-thoughts.SKILL](https://github.com/JularDepick/user-thoughts.SKILL)**: Source for the `user-thoughts` skill - persistent project idea repository workflows for capturing decisions, tech stack notes, UI/UX rationale, and MDBASE-backed project memory (MIT).
+- **[TheaDust/lore](https://github.com/TheaDust/lore)**: Source for the `lore` skill - Markdown-only, zero-dependency long-term project memory for AI coding agents, with monorepo scopes, two-section platform mirrors, and stdlib Python helpers (MIT).
 - **[ZeroPointRepo/youtube-skills](https://github.com/ZeroPointRepo/youtube-skills)**: Source for the `youtube-full` skill - TranscriptAPI-backed YouTube transcripts, search, channel browsing, playlists, and cloud-safe video research workflows (MIT).
 - **[ejentum/ejentum-mcp](https://github.com/ejentum/ejentum-mcp)**: Source for the `ejentum-reasoning-harness` skill - MCP cognitive harness modes for reasoning, code review, anti-deception checks, and memory-drift analysis (MIT).
 - **[luoyuctl/agenttrace](https://github.com/luoyuctl/agenttrace)**: Source for the `agenttrace-session-audit` skill - local AI coding-agent session audits for cost spikes, tool failures, latency gaps, anomalies, health gates, and session diffs (MIT).
@@ -423,6 +444,7 @@ Key source families include:
 - **[Elkidogz/technical-change-skill](https://github.com/Elkidogz/technical-change-skill)**: Source for the Technical Change Tracker skill - structured JSON change records, session handoff, and accessible HTML dashboards for coding continuity.
 - **[vipin-si/article-illustrations](https://github.com/vipin-si/article-illustrations)**: Source for the `article-illustrations` skill - Grav-style hand-drawn article illustrations with whiteboard sketches, sparse annotations, and visual metaphor QA guidance (MIT).
 - **[274326424/video-content-extractor](https://github.com/274326424/video-content-extractor)**: Source for the `video-content-extractor` skill - FFmpeg and Tesseract OCR workflows for extracting timestamped screen text and structured Markdown reports from MP4 videos (MIT).
+- **[metrox-eth/quit-sponsor](https://github.com/metrox-eth/quit-sponsor)**: Source for the `quit-sponsor` skill - evidence-based quit-smoking sponsorship for agents with persistent memory: 44-source cited protocols, sponsor decision tree, three-clause contract, wave protocol, slip attribution coaching, and a timestamped logbook (MIT).
 - **[rmyndharis/antigravity-skills](https://github.com/rmyndharis/antigravity-skills)**: For the massive contribution of 300+ Enterprise skills and the catalog generation logic.
 - **[amartelr/antigravity-workspace-manager](https://github.com/amartelr/antigravity-workspace-manager)**: Workspace Manager CLI companion to dynamically auto-provision subsets of skills across local development environments.
 - **[obra/superpowers](https://github.com/obra/superpowers)**: The original "Superpowers" by Jesse Vincent.
@@ -482,7 +504,7 @@ Key source families include:
 - **[christopherlhammer11-ai/tool-use-guardian](https://github.com/christopherlhammer11-ai/tool-use-guardian)**: Source for the Tool Use Guardian skill — tool-call reliability wrapper with retries, recovery, and failure classification.
 - **[christopherlhammer11-ai/recallmax](https://github.com/christopherlhammer11-ai/recallmax)**: Source for the RecallMax skill — long-context memory, summarization, and conversation compression for agents.
 - **[tsilverberg/webapp-uat](https://github.com/tsilverberg/webapp-uat)**: Full browser UAT skill — Playwright testing with console/network error capture, WCAG 2.2 AA accessibility checks, i18n validation, responsive testing, and P0-P3 bug triage. Read-only by default, works with React, Vue, Angular, Ionic, Next.js.
-- **[Wolfe-Jam/faf-skills](https://github.com/Wolfe-Jam/faf-skills)**: AI-context and project DNA skills — .faf format management, AI-readiness scoring, bi-sync, MCP server building, and championship-grade testing (17 skills, MIT).
+- **[Wolfe-Jam/faf-skills](https://github.com/Wolfe-Jam/faf-skills)**: AI-context and project DNA skills — .faf format management, AI-readiness scoring, bi-sync, MCP server building, and championship-grade testing (7 skills, MIT).
 - **[fullstackcrew-alpha/privacy-mask](https://github.com/fullstackcrew-alpha/privacy-mask)**: Local image privacy masking for AI coding agents. Detects and redacts PII, API keys, and secrets in screenshots via OCR + 47 regex rules. Claude Code hook integration for automatic masking. Supports Tesseract and RapidOCR. 100% offline (MIT).
 - **[AvdLee/SwiftUI-Agent-Skill](https://github.com/AvdLee/SwiftUI-Agent-Skill)**: SwiftUI best-practices skill for agent workflows (MIT).
 - **[CloudAI-X/threejs-skills](https://github.com/CloudAI-X/threejs-skills)**: Three.js-focused skill collection for agent-assisted 3D web work.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-awesome-skills",
-  "version": "14.2.0",
-  "description": "1,946+ agentic skills for Claude Code, Gemini CLI, Cursor, Antigravity & more. Installer CLI.",
+  "version": "14.3.0",
+  "description": "1,948+ agentic skills for Claude Code, Gemini CLI, Cursor, Antigravity & more. Installer CLI.",
   "license": "MIT",
   "scripts": {
     "validate": "node tools/scripts/run-python.js tools/scripts/validate_skills.py",
@@ -34,6 +34,9 @@
     "build": "npm run chain && npm run catalog",
     "check:stale-claims": "node tools/scripts/run-python.js tools/scripts/check_stale_claims.py",
     "check:live-seo": "node tools/scripts/check-live-seo-geo.js",
+    "pages:redirect-bridge": "node tools/scripts/generate-pages-redirect-bridge.js",
+    "traffic:normalize": "node tools/scripts/normalize_traffic_snapshots.js",
+    "traffic:migration-readiness": "node tools/scripts/audit_search_migration_readiness.js",
     "check:warning-budget": "node tools/scripts/run-python.js tools/scripts/check_validation_warning_budget.py",
     "check:readme-credits": "node tools/scripts/run-python.js tools/scripts/check_readme_credits.py",
     "audit:consistency": "node tools/scripts/run-python.js tools/scripts/audit_consistency.py",

package/tools/bin/install.js

@@ -41,7 +41,9 @@ function parseArgs(argv = process.argv.slice(2)) {
   let riskArg = null;
   let categoryArg = null;
   let tagsArg = null;
+  let skillsArg = null;
   let versionInfo = false;
+  let dryRun = false;
   let cursor = false,
     claude = false,
     gemini = false,
@@ -56,7 +58,7 @@ function parseArgs(argv = process.argv.slice(2)) {
       versionInfo = true;
       continue;
     }
-    if (["--path", "--release", "--tag", "--risk", "--category", "--tags"].includes(a[i])) {
+    if (["--path", "--release", "--tag", "--risk", "--category", "--tags", "--skills"].includes(a[i])) {
       const value = a[i + 1];
       if (!value || value.startsWith("--")) {
         throw new Error(`Option ${a[i]} requires a value.`);
@@ -67,9 +69,14 @@ function parseArgs(argv = process.argv.slice(2)) {
       if (a[i] === "--risk") riskArg = value;
       if (a[i] === "--category") categoryArg = value;
       if (a[i] === "--tags") tagsArg = value;
+      if (a[i] === "--skills") skillsArg = value;
       i += 1;
       continue;
     }
+    if (a[i] === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
     if (a[i] === "--cursor") {
       cursor = true;
       continue;
@@ -109,7 +116,9 @@ function parseArgs(argv = process.argv.slice(2)) {
     riskArg,
     categoryArg,
     tagsArg,
+    skillsArg,
     versionInfo,
+    dryRun,
     cursor,
     claude,
     gemini,
@@ -179,6 +188,8 @@ Options:
   --risk <csv>     Install only skills matching these risk labels
   --category <csv> Install only skills matching these categories
   --tags <csv>     Install only skills matching these tags
+  --skills <csv>   Set exact managed skill names, ids, or nested skill paths
+  --dry-run        Preview installs/updates/removals for every target without writing
   --version        Print the installer version
   --release <ver>  Clone tag v<ver> (e.g. 4.6.0 -> v4.6.0)
   --tag <tag>      Clone this tag or branch (e.g. v4.6.0, main)
@@ -191,6 +202,7 @@ Examples:
   npx agentic-awesome-skills --agy
   npx agentic-awesome-skills --path .agents/skills --category development,backend --risk safe,none
   npx agentic-awesome-skills --path .agents/skills --tags debugging,typescript-legacy-
+  npx agentic-awesome-skills --codex --skills frontend-design,game-development/2d-games --dry-run
   npx agentic-awesome-skills --release 4.6.0
   npx agentic-awesome-skills --path ./my-skills
   npx agentic-awesome-skills --claude --codex    Install to multiple targets
@@ -230,6 +242,19 @@ function parseSelectorArg(raw) {
   };
 }
 
+function parseExactSkillArg(raw) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    return [];
+  }
+
+  const values = raw.split(",").map((value) => value.trim());
+  if (values.some((value) => !value)) {
+    throw new Error("--skills must be a comma-separated list of non-empty exact skill names, ids, or paths.");
+  }
+
+  return uniqueValues(values);
+}
+
 function hasActiveSelector(selector) {
   return selector.include.length > 0 || selector.exclude.length > 0;
 }
@@ -422,21 +447,51 @@ function replaceManagedEntry(
 }
 
 /** Copy contents of repo's skills/ into target so each skill is target/skill-name/ (for Claude Code etc.). */
-function getInstallEntries(tempDir, selectors = buildInstallSelectors({})) {
+function resolveExactSkillSelections(repoSkills, skillEntries, requestedSkills = []) {
+  if (requestedSkills.length === 0) {
+    return null;
+  }
+
+  const skills = skillEntries.map((skillId) => readSkill(repoSkills, skillId));
+  const resolvedEntries = new Set();
+
+  for (const requestedSkill of requestedSkills) {
+    const matches = skills.filter((skill) => (
+      skill.name === requestedSkill ||
+      skill.id === requestedSkill ||
+      path.basename(skill.id) === requestedSkill
+    ));
+
+    if (matches.length === 0) {
+      throw new Error(`Unknown skill requested by --skills: ${requestedSkill}`);
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `Ambiguous skill requested by --skills: ${requestedSkill}. Use one exact nested skill path: ${matches.map((skill) => skill.id).join(", ")}`,
+      );
+    }
+
+    resolvedEntries.add(matches[0].id);
+  }
+
+  return resolvedEntries;
+}
+
+function getInstallEntries(tempDir, selectors = buildInstallSelectors({}), requestedSkills = []) {
   const repoSkills = path.join(tempDir, "skills");
   if (!fs.existsSync(repoSkills)) {
-    console.error("Cloned repo has no skills/ directory.");
-    process.exit(1);
+    throw new Error("Cloned repo has no skills/ directory.");
   }
 
   const skillEntries = listSkillIdsRecursive(repoSkills);
-  const filteredEntries = hasInstallSelectors(selectors)
-    ? skillEntries.filter((skillId) => matchesInstallSelectors(readSkill(repoSkills, skillId), selectors))
-    : skillEntries;
-
-  if (hasInstallSelectors(selectors) && filteredEntries.length === 0) {
-    console.error("No skills matched the requested --risk/--category/--tags filters.");
-    process.exit(1);
+  const selectedEntries = resolveExactSkillSelections(repoSkills, skillEntries, requestedSkills);
+  const filteredEntries = skillEntries.filter((skillId) => (
+    (!selectedEntries || selectedEntries.has(skillId)) &&
+    (!hasInstallSelectors(selectors) || matchesInstallSelectors(readSkill(repoSkills, skillId), selectors))
+  ));
+
+  if ((selectedEntries || hasInstallSelectors(selectors)) && filteredEntries.length === 0) {
+    throw new Error("No skills matched the requested --skills/--risk/--category/--tags selection.");
   }
 
   const entries = [...filteredEntries];
@@ -550,6 +605,22 @@ function readInstallManifest(targetPath) {
   }
 }
 
+function normalizeManifestEntries(entries) {
+  const normalized = [];
+  const invalid = [];
+  for (const entry of entries) {
+    try {
+      normalized.push(normalizeInstallEntry(entry));
+    } catch (error) {
+      invalid.push(entry);
+    }
+  }
+  return {
+    entries: uniqueValues(normalized).sort(),
+    invalid: uniqueValues(invalid).sort(),
+  };
+}
+
 function writeInstallManifest(targetPath, installEntries) {
   const manifestPath = resolveInstallManifestPath(targetPath);
   const normalizedEntries = [...new Set(installEntries.map(normalizeInstallEntry).filter(Boolean))].sort();
@@ -572,14 +643,17 @@ function writeInstallManifest(targetPath, installEntries) {
 
 function pruneRemovedEntries(targetPath, previousEntries, installEntries) {
   const next = new Set(installEntries.map(normalizeInstallEntry));
-  for (const entry of previousEntries) {
-    const normalizedEntry = normalizeInstallEntry(entry);
+  const normalizedPrevious = normalizeManifestEntries(previousEntries);
+  for (const entry of normalizedPrevious.invalid) {
+    console.warn(`  Skipping unsafe managed entry path from manifest: ${entry}`);
+  }
+  for (const normalizedEntry of normalizedPrevious.entries) {
     if (next.has(normalizedEntry)) {
       continue;
     }
-    const candidate = resolveManagedPath(targetPath, entry);
+    const candidate = resolveManagedPath(targetPath, normalizedEntry);
     if (!candidate) {
-      console.warn(`  Skipping unsafe managed entry path from manifest: ${entry}`);
+      console.warn(`  Skipping unsafe managed entry path from manifest: ${normalizedEntry}`);
       continue;
     }
     assertSafeDestinationPath(candidate, targetPath);
@@ -658,7 +732,16 @@ function resolveInstallRef(opts) {
   return DEFAULT_RELEASE_REF;
 }
 
-function installForTarget(tempDir, target, selectors = buildInstallSelectors({})) {
+function installForTarget(
+  tempDir,
+  target,
+  selectors = buildInstallSelectors({}),
+  installEntries = null,
+  requestedSkills = [],
+) {
+  // Resolve all selection errors before creating or changing the target.
+  const resolvedInstallEntries = installEntries || getInstallEntries(tempDir, selectors, requestedSkills);
+
   if (fs.existsSync(target.path)) {
     ensureTargetIsDirectory(target.path);
     const targetStats = fs.lstatSync(target.path);
@@ -698,10 +781,9 @@ function installForTarget(tempDir, target, selectors = buildInstallSelectors({})
     fs.mkdirSync(target.path, { recursive: true });
   }
 
-  const installEntries = getInstallEntries(tempDir, selectors);
-  const managedEntries = getManagedEntries(installEntries, target);
+  const managedEntries = getManagedEntries(resolvedInstallEntries, target);
   const previousEntries = readInstallManifest(target.path);
-  installSkillsIntoTarget(tempDir, target.path, installEntries);
+  installSkillsIntoTarget(tempDir, target.path, resolvedInstallEntries);
   pruneRemovedEntries(target.path, previousEntries, managedEntries);
   writeInstallManifest(target.path, managedEntries);
   console.log(`  ✓ Installed to ${target.path}`);
@@ -737,7 +819,7 @@ function getPostInstallMessages(targets, selectors = buildInstallSelectors({}))
 
   if (targets.some((target) => isOpenCodeStylePath(target.path))) {
     const baseMessage =
-      "For Antigravity 2.0, OpenCode, or other .agents/skills installs, prefer a reduced install with --risk, --category, or --tags to avoid context overload.";
+      "For Antigravity 2.0, OpenCode, or other .agents/skills installs, prefer a reduced install with --skills, --risk, --category, or --tags to avoid context overload.";
     messages.push(baseMessage);
     if (!hasInstallSelectors(selectors)) {
       messages.push(
@@ -749,6 +831,82 @@ function getPostInstallMessages(targets, selectors = buildInstallSelectors({}))
   return messages;
 }
 
+function buildDryRunTargetPlan(target, installEntries) {
+  const desiredEntries = uniqueValues(getManagedEntries(installEntries, target)).sort();
+  const targetExists = fs.existsSync(target.path);
+
+  if (targetExists) {
+    const stats = fs.lstatSync(target.path);
+    if (stats.isSymbolicLink()) {
+      throw new Error(`Refusing to preview through symlinked target: ${target.path}`);
+    }
+    if (!stats.isDirectory()) {
+      throw new Error(`Install path exists but is not a directory: ${target.path}`);
+    }
+  }
+
+  const previous = normalizeManifestEntries(readInstallManifest(target.path));
+  const desiredSet = new Set(desiredEntries);
+  const remove = previous.entries.filter((entry) => !desiredSet.has(entry));
+
+  // Match the apply-time destination checks without creating any path. This
+  // makes the preview fail before a later install could encounter a symlinked
+  // managed destination or an unsafe stale manifest entry.
+  for (const entry of [...desiredEntries, ...remove]) {
+    const candidate = resolveManagedPath(target.path, entry);
+    if (!candidate) {
+      throw new Error(`Refusing unsafe managed entry in dry-run plan: ${entry}`);
+    }
+    assertSafeDestinationPath(candidate, target.path);
+  }
+
+  return {
+    name: target.name,
+    path: target.path,
+    targetExists,
+    replacesRepositoryClone: targetExists && fs.existsSync(path.join(target.path, ".git")),
+    installOrUpdate: desiredEntries,
+    remove,
+    ignoredUnsafeManifestEntries: previous.invalid,
+  };
+}
+
+function buildDryRunPlan(ref, targets, installEntries) {
+  return {
+    ref: ref || "default release",
+    targets: targets.map((target) => buildDryRunTargetPlan(target, installEntries)),
+    skills: installEntries.filter((entry) => entry !== "docs").sort(),
+  };
+}
+
+function printDryRunPlan(plan) {
+  console.log("\nDry run: no target files or directories will be created, changed, or removed.");
+  console.log(`Ref: ${plan.ref}`);
+  console.log(`Exact skill set (${plan.skills.length}):`);
+  for (const skill of plan.skills) {
+    console.log(`  ${skill}`);
+  }
+  console.log("Target mutation plans:");
+  for (const target of plan.targets) {
+    console.log(`  ${target.name}: ${target.path}`);
+    console.log(`    target: ${target.targetExists ? "existing directory" : "will be created"}`);
+    if (target.replacesRepositoryClone) {
+      console.log("    migration: existing repository clone will be backed up and replaced");
+    }
+    console.log(`    install/update managed entries (${target.installOrUpdate.length}):`);
+    for (const entry of target.installOrUpdate) {
+      console.log(`      ${entry}`);
+    }
+    console.log(`    remove stale managed entries (${target.remove.length}):`);
+    for (const entry of target.remove) {
+      console.log(`      ${entry}`);
+    }
+    for (const entry of target.ignoredUnsafeManifestEntries) {
+      console.log(`    ignored unsafe manifest entry: ${entry}`);
+    }
+  }
+}
+
 function main() {
   let opts;
   try {
@@ -759,6 +917,14 @@ function main() {
     return;
   }
   const selectors = buildInstallSelectors(opts);
+  let requestedSkills;
+  try {
+    requestedSkills = parseExactSkillArg(opts.skillsArg);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
   const ref = resolveInstallRef(opts);
 
   if (opts.help) {
@@ -788,10 +954,38 @@ function main() {
     }
     run("git", buildCloneArgs(REPO, tempDir, ref));
 
+    // Resolve the exact set once before touching any target. This keeps an
+    // unknown/ambiguous --skills value or an empty filter intersection atomic
+    // across multi-target installs.
+    let installEntries;
+    try {
+      installEntries = getInstallEntries(tempDir, selectors, requestedSkills);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    // Preflight every target before mutating the first one. The same plan is
+    // printed for --dry-run and acts as the multi-target safety gate for apply.
+    let dryRunPlan;
+    try {
+      dryRunPlan = buildDryRunPlan(ref, targets, installEntries);
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (opts.dryRun) {
+      printDryRunPlan(dryRunPlan);
+      return;
+    }
+
     console.log(`\nInstalling for ${targets.length} target(s):`);
     for (const target of targets) {
       console.log(`\n${target.name}:`);
-      installForTarget(tempDir, target, selectors);
+      installForTarget(tempDir, target, selectors, installEntries);
     }
 
     for (const message of getPostInstallMessages(targets, selectors)) {
@@ -821,6 +1015,8 @@ module.exports = {
   replaceManagedEntry,
   getPostInstallMessages,
   buildCloneArgs,
+  buildDryRunPlan,
+  buildDryRunTargetPlan,
   buildInstallSelectors,
   getInstallEntries,
   getManagedEntries,
@@ -831,10 +1027,14 @@ module.exports = {
   main,
   matchesInstallSelectors,
   normalizeInstallEntry,
+  normalizeManifestEntries,
+  parseExactSkillArg,
   parseSelectorArg,
+  printDryRunPlan,
   parseArgs,
   pruneRemovedEntries,
   readInstallManifest,
+  resolveExactSkillSelections,
   resolveInstallRef,
   writeInstallManifest,
 };