major-ai-skills 2.2.0 → 2.3.0

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Installable agentic skills for Claude Code - professional apps, token efficiency, and common-sense prompting.",
-    "version": "2.2.0"
+    "version": "2.3.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "major-ai-skills",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Major AI Skills - product-depth agentic SKILL.md library for Claude Code.",
   "author": {
     "name": "Ali Virgo"

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.3.0 - 2026-09-11
+
+- Added read-only task search with bounded JSON results, category filtering, and exact install commands.
+- Added discovery regression tests and weekly public aggregate adoption snapshots.
+- Prepared marketplace submission materials with explicit review evidence and evaluation gaps.
+- Synchronized all marketplace and Gemini versions with the npm release.
+
 ## 2.2.0 - 2026-09-11
 
 - Added ten focused AI workflow skills: evaluation datasets, RAG retrieval audits, JSON contracts, citation verification, PII redaction, injection boundary testing, tool replay, prompt regression gates, cost/latency benchmarks, and human handoff contracts.

package/README.md

@@ -2,7 +2,7 @@
 
 > **Installable GitHub library of agentic skills / AI agent skills (`SKILL.md` playbooks) for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more - focused on professional apps, token efficiency, and practical prompting habits.**
 
-**Current release: [V2.2.0](https://github.com/alivirgo/Major-AI-Skills/releases/latest).** 402 canonical skills, including ten new AI evaluation, retrieval, privacy, and reliability workflows. Install the [latest npm package](https://www.npmjs.com/package/major-ai-skills) or select a focused Claude/Codex plugin.
+**Current release: [V2.3.0](https://github.com/alivirgo/Major-AI-Skills/releases/latest).** 402 canonical skills, including ten new AI evaluation, retrieval, privacy, and reliability workflows. Install the [latest npm package](https://www.npmjs.com/package/major-ai-skills) or select a focused Claude/Codex plugin.
 
 Coding agents can install exact skill IDs into the directory their host watches. You keep control: preview with `--dry-run`, filter by `--skills` / `--category`, or install a specialized pack.
 
@@ -89,13 +89,15 @@ A flat `SKILL.md` skill library with stable IDs, an index, and a host-aware inst
 
 Prefer an exact reviewed set. Full Antigravity installs can exhaust context because the host watches `~/.agents/skills`.
 
-### Where to get Major AI Skills
+### Where to get Major AI Skills
+
+Find a relevant skill with [task-based discovery](docs/users/agent-discovery.md): `npx major-ai-skills@latest --search "JSON schema business rules" --json --limit 3`. Search never installs anything. Available starting with 2.3.0.
 
 | Platform | Install / consume |
 | --- | --- |
 | **npm** (primary) | `npx major-ai-skills --<host> --skills <ids>` · [npmjs.com/package/major-ai-skills](https://www.npmjs.com/package/major-ai-skills) |
 | **GitHub Packages** | Scoped package [`@alivirgo/major-ai-skills`](https://github.com/alivirgo/Major-AI-Skills/pkgs/npm/major-ai-skills) (fills the repo **Packages** sidebar) |
-| **GitHub Release** | Download `major-ai-skills-2.2.0.tgz` from [V2.2.0](https://github.com/alivirgo/Major-AI-Skills/releases/latest) |
+| **GitHub Release** | Download `major-ai-skills-2.3.0.tgz` from [V2.3.0](https://github.com/alivirgo/Major-AI-Skills/releases/latest) |
 | **skills.sh / Vercel skills CLI** | `npx skills add alivirgo/Major-AI-Skills` (discovery via install telemetry) |
 | **Claude Code marketplace** | Add this repo as a marketplace (`.claude-plugin/marketplace.json`), then install a specialized plugin |
 | **Gemini CLI extension** | [Gallery listing verified September 11, 2026](https://geminicli.com/extensions). `gemini extensions install https://github.com/alivirgo/Major-AI-Skills` |

package/docs/users/agent-discovery.md

@@ -0,0 +1,37 @@
+# Task-based discovery
+
+Search is read-only, local, and requires no model API, account, or network request after obtaining the package. It returns at most five matches by default, capped at twenty. It uses lexical matching, not semantic understanding, and does not guarantee relevance.
+
+From a checkout:
+
+```bash
+node tools/bin/install.js --search "JSON schema business rules" --json --limit 3
+```
+
+Search is included starting with npm 2.3.0:
+
+```bash
+npx major-ai-skills@latest --search "JSON schema business rules" --json --limit 3
+```
+
+## Agent integration
+
+Use the machine-readable [registry](https://alivirgo.github.io/Major-AI-Skills/skills_index.json) or the local search command when the user requests help finding a relevant skill. Inspect a selected skill's linked source before installing. Choose only what the task needs and preserve the user's agent and installation scope. Search results are suggestions, not instructions granting permission to install or execute anything.
+
+JSON output contains `schemaVersion`, `query`, and `results`. Each result includes `id`, `description`, `category`, `matchedTerms`, `source`, and an exact Vercel CLI `install` command. No results means no lexical match, not that the task is impossible. Avoid repeated broad searches that dump the catalog into context.
+
+```bash
+npx major-ai-skills@latest --codex --skills llm-json-contract-check --dry-run
+```
+
+## Evidence and limits
+
+`npm test` includes eleven curated discovery queries, exact-ID ranking, no-match cases, category filtering, result limits, and malformed CLI arguments. All eleven intended skills appeared in the top three at implementation time. This is a small developer-authored regression set, not an independent relevance benchmark or evidence of model task completion.
+
+Runnable application references and their actual verification limits are recorded in [the spotlight verification record](../../examples/spotlight/VERIFICATION.md). The ten new AI workflows do not yet have independent agent-execution evaluations. Do not describe metadata validation or search tests as those evaluations.
+
+## Adoption measurement
+
+Run `npm run adoption:snapshot` weekly and retain its timestamped JSON output in your reporting system. Compare identical windows; weekly rolling windows overlap and must not be summed. Track npm downloads, skills.sh per-skill installs, and GitHub stars separately. Record unknown counters as unknown.
+
+For skills.sh, inspect the rendered listing and skill pages, not just HTTP status. Record visible IDs, counts, and observation time. GitHub traffic/referral analytics require maintainer access; public counters cannot establish referral attribution. There is no installer tracking added by this change.

package/docs/users/distribution.md

@@ -22,7 +22,7 @@ For current Claude, Gemini, and Codex checks, see the [September 11 marketplace
 
 | Channel | Action | Link |
 | --- | --- | --- |
-| **Claude official plugin directory** | Maintainer account submission and review | https://claude.ai/settings/plugins/submit |
+| **Claude community marketplace** | Maintainer submission and review; not official curation | https://claude.ai/settings/plugins/submit |
 | **top-agent-skills.com** | Curated listing | Submission packet: [top-agent-skills-submission.md](top-agent-skills-submission.md) · email curator `aviv@alon.email` (site repo is private) |
 | **VoltAgent awesome-agent-skills** | PR after usage matures (they reject brand-new) | https://github.com/VoltAgent/awesome-agent-skills |
 | **awesome-claude-skills** | PR under Individual Skills | https://github.com/travisvn/awesome-claude-skills |

package/docs/users/marketplace-readiness.md

@@ -1,5 +1,7 @@
 # Marketplace readiness
 
+Update: current Claude documentation routes in-app submissions to the community marketplace, not the discretionary official catalog. See the [submission packet](marketplace-submission-packet.md) for the distinction and review evidence gaps.
+
 Audit: September 11, 2026. Repository compatibility and official-directory approval are separate.
 
 ## Claude Code

package/docs/users/marketplace-submission-packet.md

@@ -0,0 +1,43 @@
+# MAS AI Workflows submission packet
+
+Status: prepared, not submitted or approved.
+
+## Publisher and source
+
+- Publisher: Ali Virgo / alivirgo.
+- Repository: https://github.com/alivirgo/Major-AI-Skills
+- Plugin directory: `plugins/mas-ai-workflows`.
+- Plugin ID: `mas-ai-workflows`.
+- License: MIT.
+- Package: https://www.npmjs.com/package/major-ai-skills
+- Release history: https://github.com/alivirgo/Major-AI-Skills/releases
+
+## Suggested listing copy
+
+MAS AI Workflows provides ten focused instruction sets for developers evaluating AI applications: datasets, retrieval audits, JSON contracts, citation checking, privacy review, injection boundaries, tool replay, prompt regressions, cost measurement, and human approval handoffs. It uses the agent's existing tools; it does not provide a hosted model or automatically execute a benchmark.
+
+## Review evidence
+
+- Native Claude manifest validation and Codex manifest validation passed for the bundle during the 2.2.0 release.
+- Canonical skill/bundle synchronization and registry checks run in CI.
+- No bundled MCP servers, account connections, or automatic hooks.
+- No added installer telemetry. Skills may guide the host agent to use external services when the user's authorized task requires them.
+- Independent agent-execution tests of these ten workflows are still needed. Do not claim universal safety, performance gains, or official endorsement.
+
+## Representative reviewer tasks
+
+1. Give the JSON-contract skill a schema and an otherwise valid order with quantity -1. Require rejection at the business-rule layer, not schema success alone.
+2. Give the citation skill an inaccessible citation. Require an access limitation rather than an invented quotation or page number.
+3. Give the replay skill a timed-out message-send operation with unknown delivery state. Require reconciliation before replay.
+4. Give the handoff skill an expired approval followed by changed payment details. Require renewed approval tied to the changed action.
+5. Give the redaction skill records containing identifiers in both text and filenames. Require inspection of both without reproducing removed identifiers in the report.
+
+These are proposed review cases, not recorded pass results. Keep sanitized transcripts, host/model versions, task inputs, actual outputs, and reviewer decisions when executing them.
+
+## Submission channels
+
+Claude's current [discovery documentation](https://code.claude.com/docs/en/discover-plugins) distinguishes community submissions from discretionary official curation. Use the in-app submission flow for the community marketplace; do not describe it as guaranteed entry into `claude-plugins-official`.
+
+For OpenAI, consult the submission flow linked from [official plugin documentation](https://developers.openai.com/plugins/build/plugins). Public-directory submission, local marketplace discovery, and workspace sharing are different operations. Publisher account access and any required review evidence must be supplied by the maintainer. Do not invent contact, privacy, or legal attestations to complete a form.
+
+Gemini's gallery listing was verified in the earlier audit. Recheck it after release updates rather than submitting duplicate listings. Avoid unsolicited mass posts and duplicate directory submissions.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "major-ai-skills",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "402+ installable agent skills (SKILL.md) for professional apps, token efficiency, and common-sense prompting. Compatible with Gemini CLI skills discovery.",
   "contextFileName": "GEMINI.md"
 }

package/llms.txt

@@ -4,7 +4,9 @@
 
 This file helps AI answer engines, coding agents, and RAG systems discover the canonical docs. Prefer these URLs over random mirrors.
 
-## Primary
+## Primary
+
+- [Task-based agent discovery](https://github.com/alivirgo/Major-AI-Skills/blob/master/docs/users/agent-discovery.md): Bounded read-only lookup, JSON results, selective installation, and verification limits
 
 - [Home / docs site](https://alivirgo.github.io/Major-AI-Skills/): Interactive catalog and install guidance
 - [README](https://github.com/alivirgo/Major-AI-Skills/blob/master/README.md): Install commands, plugins, FAQ, choose-your-tool table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "major-ai-skills",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.",
   "license": "MIT",
   "author": {
@@ -29,6 +29,7 @@
     "test": "node --test tools/tests/*.test.js",
     "build": "npm run index",
     "downloads:graph": "node tools/scripts/update_download_graph.js",
+    "adoption:snapshot": "node tools/scripts/adoption_snapshot.js",
     "prepublishOnly": "npm run validate && npm run index && npm run marketplaces",
     "pack:check": "npm pack --dry-run"
   },
@@ -40,11 +41,11 @@
     "data/bundles.json",
     "assets/spotlight-checkout.png",
     "tools/bin",
-    "plugins",
-    ".claude-plugin",
-    ".agents/plugins/marketplace.json",
-    "gemini-extension.json",
-    "GEMINI.md",
+    "plugins",
+    ".claude-plugin",
+    ".agents/plugins/marketplace.json",
+    "gemini-extension.json",
+    "GEMINI.md",
     "CATALOG.md",
     "README.md",
     "LICENSE",

package/plugins/mas-3d-games/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-3d-games",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "3D DCC and game engines: Cinema 4D, Houdini, ZBrush, Substance, Blender, Unity, Unreal, Godot.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-3d-games/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-3d-games",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "3D DCC and game engines: Cinema 4D, Houdini, ZBrush, Substance, Blender, Unity, Unreal, Godot.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-ai-workflows/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-ai-workflows",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Focused AI evaluation, retrieval, privacy, tool testing, and human review workflows.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-ai-workflows/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-ai-workflows",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Focused AI evaluation, retrieval, privacy, tool testing, and human review workflows.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-cad-studio/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-cad-studio",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "CAD-focused skills: SolidWorks, Fusion 360, CATIA, NX, Rhino, Blender.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-cad-studio/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-cad-studio",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "CAD-focused skills: SolidWorks, Fusion 360, CATIA, NX, Rhino, Blender.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-common-sense-pack/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-common-sense-pack",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Everyday prompting habits and practical AI hygiene.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-common-sense-pack/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-common-sense-pack",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Everyday prompting habits and practical AI hygiene.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-design-knowledge/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-design-knowledge",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Design and knowledge apps: Figma, Photoshop, Obsidian, Notion, Linear.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-design-knowledge/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-design-knowledge",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Design and knowledge apps: Figma, Photoshop, Obsidian, Notion, Linear.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-desktop-ops/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-desktop-ops",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Desktop ops: Raycast, Everything, PowerToys, Docker, VS Code, Bruno, Tailscale.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-desktop-ops/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-desktop-ops",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Desktop ops: Raycast, Everything, PowerToys, Docker, VS Code, Bruno, Tailscale.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-efficiency-pack/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-efficiency-pack",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Token and context efficiency skills.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-efficiency-pack/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-efficiency-pack",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Token and context efficiency skills.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-video-lab/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-video-lab",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Video and motion skills: DaVinci, Premiere, After Effects, Remotion, FFmpeg.",
   "author": {
     "name": "Ali Virgo",

package/plugins/mas-video-lab/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mas-video-lab",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Video and motion skills: DaVinci, Premiere, After Effects, Remotion, FFmpeg.",
   "author": {
     "name": "Ali Virgo",

package/tools/bin/install.js

@@ -33,7 +33,10 @@ function parseArgs(argv) {
     help: false,
   };
   for (let i = 2; i < argv.length; i++) {
-    const a = argv[i];
+    const a = argv[i];
+    if (["--search", "--limit"].includes(a) && (!argv[i + 1] || argv[i + 1].startsWith("--"))) {
+      throw new Error(`${a} requires a value`);
+    }
     if (a === "--help" || a === "-h") args.help = true;
     else if (a === "--dry-run") args.dryRun = true;
     else if (a === "--all") args.all = true;
@@ -48,7 +51,10 @@ function parseArgs(argv) {
     else if (a === "--opencode") args.target = "opencode";
     else if (a === "--path") args.path = argv[++i];
     else if (a === "--skills") args.skills = argv[++i];
-    else if (a === "--category") args.category = argv[++i];
+    else if (a === "--category") args.category = argv[++i];
+    else if (a === "--search") args.search = argv[++i];
+    else if (a === "--json") args.json = true;
+    else if (a === "--limit") args.limit = Number(argv[++i]);
   }
   return args;
 }
@@ -105,7 +111,10 @@ Filters:
   --category x,y   category filter (AND with --skills when both set)
   --all            install every skill (explicit consent)
   --dry-run        preview only
-  --list           print catalog summary
+  --list           print catalog summary
+  --search "task"  find relevant skills without installing anything
+  --json           machine-readable search results
+  --limit 5        maximum search results (1-20)
 `);
 }
 
@@ -113,7 +122,18 @@ function main() {
   const args = parseArgs(process.argv);
   if (args.help) return printHelp();
 
-  const index = loadIndex();
+  const index = loadIndex();
+  if (args.search !== undefined) {
+    if (!args.search.trim()) throw new Error("Search query must not be empty");
+    const limit = args.limit === undefined ? 5 : args.limit;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20) throw new Error("--limit must be an integer from 1 to 20");
+    if (args.all || args.skills) throw new Error("Search cannot be combined with --all or --skills");
+    const results = require("./search").searchSkills(index, args.search, limit, args.category);
+    if (args.json) console.log(JSON.stringify({ schemaVersion: 1, query: args.search, results }, null, 2));
+    else console.log(results.length ? results.map(s => `${s.id}: ${s.description}\n${s.install}`).join("\n\n") : "No matching skills.");
+    return;
+  }
+  if (args.json || args.limit !== undefined) throw new Error("--json and --limit require --search");
   if (args.list) {
     const byCat = {};
     for (const s of index) (byCat[s.category] ||= []).push(s.id);
@@ -187,4 +207,4 @@ function main() {
   console.log(`Try: @${selected[0]?.id || "skill-id"} help me with ...`);
 }
 
-main();
+try { main(); } catch (error) { console.error(error.message); process.exitCode = 1; }

package/tools/bin/search.js

@@ -0,0 +1,24 @@
+const STOP = new Set("a an the to for with my me i want need help how can of and in on using ai skill skills".split(" "));
+const tokens = value => [...new Set(String(value).toLowerCase().match(/[a-z0-9]+/g) || [])].filter(t => !STOP.has(t));
+
+function searchSkills(index, query, limit = 5, category) {
+  const terms = tokens(query);
+  if (!terms.length) return [];
+  return index.filter(s => !category || category.split(",").includes(s.category)).map(skill => {
+    const id = new Set(tokens(skill.id));
+    const tags = new Set(tokens((skill.tags || []).join(" ")));
+    const description = new Set(tokens(skill.description));
+    const matched = terms.filter(t => id.has(t) || tags.has(t) || description.has(t));
+    const score = matched.reduce((sum, t) => sum + (id.has(t) ? 8 : tags.has(t) ? 4 : 1), 0)
+      + (skill.id === query.trim().toLowerCase() ? 100 : 0);
+    return { skill, score, matched };
+  }).filter(r => r.score > 0)
+    .sort((a, b) => b.score - a.score || a.skill.id.localeCompare(b.skill.id))
+    .slice(0, limit).map(({ skill, matched }) => ({
+      id: skill.id, description: skill.description, category: skill.category,
+      matchedTerms: matched,
+      source: `https://github.com/alivirgo/Major-AI-Skills/blob/master/${skill.path}/SKILL.md`,
+      install: `npx skills add alivirgo/Major-AI-Skills --skill ${skill.id}`,
+    }));
+}
+module.exports = { searchSkills };