showdar-skills 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.3.0]
+
+### Added
+
+- Explicit harness targets for `showdar init` and `showdar add`: `codex`,
+  `opencode`, `cursor`, `claude`, `universal`, and `all`.
+- `showdar add <skill>` for installing a single primitive skill without
+  re-running a whole profile (for example `showdar add debug`,
+  `showdar add security --ai cursor`,
+  `showdar add review --scope global --ai claude`).
+- Native Cursor skill roots (`.cursor/skills` for projects,
+  `~/.cursor/skills` for global installs).
+- Deny-by-default routing authority coverage for conditional, modal,
+  contextual, hypothetical, and negated actions.
+
+### Changed
+
+- Each harness target now installs into its native skill directory instead of
+  sharing one compatibility root.
+- Routing uses a single authoritative engine: current request → structural
+  interpretation → authority classification → primary capability → skill.
+- Context, log, and example text no longer becomes requested work on its own;
+  conditional and hypothetical actions stay non-authoritative until current
+  request semantics permit them.
+- Risk metadata no longer overrides an explicit governing action.
+
+### Fixed
+
+- Conditional, modal, context, and negation authority safety cases.
+- Security-risk ownership cases where risk signals previously stole primary
+  ownership from the governing action.
+- Debug, upgrade, build, and test imperative recognition for explicit
+  governing requests.
+
+### Removed
+
+- The executable legacy 6F authority engine and the old route-scoring path.
+
+## [0.2.3]
+
+See git history for changes before the 0.3.0 changelog was started.

package/MIGRATION.md

@@ -0,0 +1,52 @@
+# Migrating to 0.3.0
+
+## Skill install roots
+
+`--ai universal` still installs to `.agents/skills` (project) and
+`~/.agents/skills` (global). Explicit harness targets now use their native
+roots:
+
+- OpenCode: `.opencode/skills` / `~/.config/opencode/skills`
+- Cursor: `.cursor/skills` / `~/.cursor/skills`
+- Claude Code: `.claude/skills` / `~/.claude/skills`
+- Codex: `.agents/skills` / `~/.agents/skills`
+
+One invocation installs to one resolved root only; no compatibility copies
+are made automatically.
+
+## Existing projects
+
+Existing `.showdar.json` v2 configs remain valid. No config-version migration
+is required. Re-running `showdar init` with an explicit `--ai` target moves
+managed skills to the newly requested native root; the previous root is not
+silently deleted unless existing Showdar stale-cleanup semantics apply.
+
+## Profiles
+
+Profile names and composition are unchanged:
+
+- `minimal` (8), `developer` (12), `backend` (14), `qa` (9), `product` (6),
+  `full` (15).
+- `mobile` and `web` remain accepted as deprecated aliases for `developer`;
+  manifests store the canonical name.
+
+## Single-skill additions
+
+Use `showdar add <skill>` instead of re-running a larger profile to add one
+skill:
+
+```bash
+showdar add debug
+showdar add security --ai cursor
+showdar add review --scope global --ai claude
+```
+
+Additions preserve the configured profile and are idempotent.
+
+## Routing behavior
+
+0.3.0 uses stricter deny-by-default authority semantics. Conditional,
+hypothetical, contextual, and negated actions stay non-authoritative until
+current request semantics permit them, and risk metadata no longer overrides
+an explicit governing action. Do not assume byte-identical routing with older
+releases where behavior intentionally tightened.

package/README.md

@@ -17,10 +17,16 @@ Install the CLI, then install a role-oriented skill profile into your project:
 ```bash
 npm install -g showdar-skills
 cd my-project
-showdar init --ai codex --profile developer
+showdar init
 showdar doctor
 ```
 
+```bash
+showdar init --ai cursor
+showdar init --ai claude --scope global
+showdar init --profile developer --ai opencode
+```
+
 To install from source instead:
 
 ```bash
@@ -29,9 +35,10 @@ cd showdar-skills
 npm install -g .
 ```
 
-Showdar works with Codex, OpenCode, Claude Code, and universal agent skill
-directories. Choose `backend`, `qa`, or `product` when that gives discovery a
-more precise context; use `full` when you want all capabilities available.
+Showdar works with Universal Agent Skills, Codex, OpenCode, Cursor, and
+Claude Code as supported installation targets. Choose `backend`, `qa`, or
+`product` when that gives discovery a more precise context; use `full` when
+you want all capabilities available.
 
 ## Why Showdar?
 
@@ -71,15 +78,23 @@ knowledge progressively.
 
 ## Supported agents
 
-| Target | Project destination | Global destination |
-| --- | --- | --- |
-| Codex / Universal | `.agents/skills/` | `~/.agents/skills/` |
-| OpenCode skills | `.opencode/skills/` | `~/.config/opencode/skills/` |
-| OpenCode commands | `.opencode/commands/showdar/` | `~/.config/opencode/commands/showdar/` |
-| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Harness | Project path | Global path | Status |
+| --- | --- | --- | --- |
+| Universal Agent Skills | `.agents/skills/` | `~/.agents/skills/` | Supported installation target |
+| Codex | `.agents/skills/` | `~/.agents/skills/` | Supported installation target |
+| OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` | Supported installation target |
+| Cursor | `.cursor/skills/` | `~/.cursor/skills/` | Supported installation target |
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` | Supported installation target |
+
+Universal uses `.agents/skills/`. Explicit harness targets use their native
+skill directories. Codex and Universal intentionally share `.agents/skills/`.
+OpenCode additionally receives native `/showdar/...` command files in
+`.opencode/commands/showdar/` (project) and
+`~/.config/opencode/commands/showdar/` (global).
 
-Codex and Universal intentionally share `.agents/skills/`. OpenCode receives
-both skills and native `/showdar/...` command files.
+"Supported installation target" means skills install to the harness-native
+directory. It does not promise identical implicit invocation, cloud,
+agent/subagent, or MCP behavior across harnesses.
 
 ## Project and global installation
 
@@ -238,10 +253,57 @@ OpenCode exposes native commands after initialization with `--ai opencode` or
 | `showdar-security` | Performs defensive, evidence-based analysis and never exposes secret values. |
 | `showdar-requirements` | Records assumptions and open decisions instead of inventing business decisions. |
 
+## Adding a single skill
+
+Install one primitive skill without re-running a whole profile:
+
+```bash
+showdar add debug
+showdar add showdar-security
+showdar add test --ai cursor
+showdar add review --scope global --ai claude
+```
+
+Accepted names are the short form (`debug`) or the canonical form
+(`showdar-debug`). The release ships exactly 15 primitive skills. `showdar add`
+is idempotent, preserves the configured profile, supports `--ai`/`--scope`
+overrides, and refuses to overwrite a foreign same-name skill directory that
+Showdar does not own.
+
+## Routing
+
+Showdar routes each request through progressive disclosure: the host discovers
+lightweight skill metadata, loads the relevant skill, and pulls deeper
+guides and data only when needed.
+
+```text
+current request
+      |
+      v
+structural interpretation
+      |
+      v
+authority classification
+      |
+      v
+primary capability
+      |
+      v
+skill
+```
+
+Product behavior notes:
+
+- Context, log, and example text does not automatically become requested work.
+- Conditional and hypothetical actions remain non-authoritative until current
+  request semantics permit them.
+- Risk metadata does not override an explicit governing action.
+
 ## CLI reference
 
 ```bash
 showdar init [--scope <project|global>] --ai <target> --profile <profile>
+showdar add <skill> [--ai <target>] [--scope <project|global>]
 showdar list
 showdar status [--scope <project|global>]
 showdar doctor [--scope <project|global>]
@@ -249,10 +311,12 @@ showdar validate
 showdar remove [--scope <project|global>]
 ```
 
-Main flags are `--ai`, `--profile`, and `--scope`. `--ai` accepts `codex`,
-`opencode`, `claude`, `universal`, or `all`. `--scope` defaults to `project`;
-`--profile` accepts the six canonical profiles and the `mobile`/`web` aliases.
-Run `showdar --help` or a command's `--help` for current options.
+Main flags are `--ai`, `--profile`, and `--scope`. `--ai` accepts `universal`,
+`codex`, `opencode`, `cursor`, `claude`, or `all` for `init` (single targets
+for `add`). `--scope` accepts `project` or `global` and defaults to `project`;
+`--profile` accepts the six canonical profiles and the deprecated
+`mobile`/`web` aliases. Run `showdar --help` or a command's `--help` for
+current options.
 
 `showdar validate` validates the installed Showdar package. `showdar doctor`
 checks managed files against ownership hashes, while `showdar remove` removes

package/bin/showdar.js

@@ -4,7 +4,7 @@ import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { AI_TARGETS, PROFILE_ALIASES, PROFILES, SKILLS, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
-import { globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, removeGlobal, removeProject } from '../src/project.js';
+import { addSkill, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, removeGlobal, removeProject } from '../src/project.js';
 import { validateRepository } from '../src/validate.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -32,14 +32,18 @@ function scopeAfter(args) {
 function printHelp(version, command = null) {
   const scopeUsage = '[--scope <project|global>]';
   if (command === 'init') {
-    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <codex|opencode|claude|universal|all>]\n\nDefaults: scope project, profile full, AI target universal.\nProject scope writes native skills and project .showdar.json. Global scope writes verified user skill directories and ~/.showdar/global.json without project files. Codex and universal use .agents/skills in project scope and ~/.agents/skills in global scope; --ai all writes each shared destination once.\n\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n\nDefaults: scope project, profile full, AI target universal.\nProject scope writes native skills and project .showdar.json. Global scope writes verified user skill directories and ~/.showdar/global.json without project files. Codex and universal use .agents/skills in project scope and ~/.agents/skills in global scope; cursor uses .cursor/skills in project scope and ~/.cursor/skills in global scope; --ai all writes each shared destination once.\n\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
     return;
   }
   if (['status', 'doctor', 'remove'].includes(command)) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar ${command} ${scopeUsage}\n\nDefault scope: project. Use --scope global for the user installation.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <codex|opencode|claude|universal|all>]\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list\n  showdar remove ${scopeUsage}\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  if (command === 'add') {
+    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
+    return;
+  }
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list\n  showdar remove ${scopeUsage}\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -55,7 +59,7 @@ async function main() {
   }
   if (args.includes('--help') || args.includes('-h')) return printHelp(version, command);
 
-  const scope = ['init', 'status', 'doctor', 'remove'].includes(command) ? scopeAfter(args) : null;
+  const scope = ['init', 'status', 'doctor', 'remove', 'add'].includes(command) ? scopeAfter(args) : null;
 
   if (command === 'list') {
     console.log(`Profiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\n\nSkills:`);
@@ -76,7 +80,7 @@ async function main() {
   }
 
   if (command === 'init') {
-    if (args.includes('--agent')) throw new Error('--agent is no longer supported in V0.2. Use --ai <codex|opencode|claude|universal|all>.');
+    if (args.includes('--agent')) throw new Error('--agent is no longer supported in V0.2. Use --ai <universal|codex|opencode|cursor|claude|all>.');
     const requestedProfile = valueAfter(args, '--profile', 'full');
     const profile = canonicalProfile(requestedProfile);
     const ai = valueAfter(args, '--ai', 'universal');
@@ -112,6 +116,25 @@ async function main() {
     return;
   }
 
+  if (command === 'add') {
+    const positional = args.filter((a, i) => i > 0 && !a.startsWith('--') && args[i - 1] !== '--ai' && args[i - 1] !== '--scope');
+    const skillArg = positional[0];
+    if (!skillArg) throw new Error('Skill name is required. Usage: showdar add <skill> [--ai <target>] [--scope <project|global>]');
+    const hasAiFlag = args.includes('--ai');
+    const hasScopeFlag = args.includes('--scope');
+    const result = await addSkill({
+      cwd: projectRoot,
+      skill: skillArg,
+      ai: hasAiFlag ? valueAfter(args, '--ai', 'universal') : null,
+      scope: hasScopeFlag ? scope : null,
+      home: homedir(),
+      packageRoot,
+      packageVersion: version,
+    });
+    console.log(`Showdar skill ${result.added ? 'added' : 'already installed'}.\nSkill: ${result.skill}\nScope: ${result.scope}\nAI: ${result.ai}\nPath: ${result.destination}`);
+    return;
+  }
+
   if (command === 'remove') {
     if (scope === 'global') await removeGlobal();
     else await removeProject(projectRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },
@@ -14,7 +14,7 @@
     "release:check": "node scripts/check-release-version.mjs"
   },
   "engines": { "node": ">=20" },
-  "files": ["bin", "src", "skills", "commands", "router", "bundles", "profiles", "engine", "README.md", "LICENSE"],
+  "files": ["bin", "src", "skills", "commands", "router", "bundles", "profiles", "engine", "README.md", "LICENSE", "CHANGELOG.md", "MIGRATION.md"],
   "keywords": ["agent-skills", "coding-agents", "codex", "opencode", "claude-code", "software-engineering", "developer-tools", "requirements", "qa", "security", "devops", "workflow"],
   "license": "MIT",
   "repository": {
@@ -24,5 +24,8 @@
   "homepage": "https://github.com/caongocquy/showdar-skills#readme",
   "bugs": {
     "url": "https://github.com/caongocquy/showdar-skills/issues"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0"
   }
 }

package/skills/showdar-review/scripts/collect-diff.mjs

@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 const cwd=process.argv[2]??process.cwd(); const base=process.argv[3]??'HEAD';
-const run=a=>{const r=spawnSync('git',a,{cwd,encoding:'utf8'});return r.status===0?r.stdout.trim():null};
-console.log(JSON.stringify({base,status:run(['status','--short']),files:run(['diff','--name-only',base])?.split('\n').filter(Boolean)??[],stat:run(['diff','--stat',base]),diff:run(['diff','--no-ext-diff','--unified=3',base])},null,2));
+const run=(args)=>{const r=spawnSync('git',args,{cwd,encoding:'utf8',shell:false});if(r.error)throw r.error;if(r.status!==0)throw new Error((r.stderr||r.stdout).trim()||`git ${args.join(' ')} failed`);return r.stdout.trim()};
+try {
+  if (base.startsWith('-')) throw new Error('revision must not begin with "-"');
+  const resolved=run(['rev-parse','--verify',`${base}^{commit}`]);
+  console.log(JSON.stringify({base,status:run(['status','--short']),files:run(['diff','--no-ext-diff','--name-only',resolved])?.split('\n').filter(Boolean)??[],stat:run(['diff','--no-ext-diff','--stat',resolved]),diff:run(['diff','--no-ext-diff','--unified=3',resolved])},null,2));
+} catch (error) {
+  console.error(`collect-diff: ${error.message}`);
+  process.exitCode=1;
+}

package/src/adapters.js

@@ -1,11 +1,12 @@
 import path from 'node:path';
 import { homedir } from 'node:os';
 
-export const NATIVE_TARGETS = ['codex', 'opencode', 'claude', 'universal'];
+export const NATIVE_TARGETS = ['codex', 'opencode', 'cursor', 'claude', 'universal'];
 
 const ROOTS = {
   codex: ['.agents', 'skills'],
   opencode: ['.opencode', 'skills'],
+  cursor: ['.cursor', 'skills'],
   claude: ['.claude', 'skills'],
   universal: ['.agents', 'skills'],
 };
@@ -13,13 +14,14 @@ const ROOTS = {
 const GLOBAL_ROOTS = {
   codex: ({ homeRoot }) => path.join(homeRoot, '.agents', 'skills'),
   opencode: ({ homeRoot }) => path.join(homeRoot, '.config', 'opencode', 'skills'),
+  cursor: ({ homeRoot }) => path.join(homeRoot, '.cursor', 'skills'),
   claude: ({ homeRoot }) => path.join(homeRoot, '.claude', 'skills'),
   universal: ({ homeRoot }) => path.join(homeRoot, '.agents', 'skills'),
 };
 
 export function resolveTargets(ai) {
   if (ai === 'all') return [...NATIVE_TARGETS];
-  if (!NATIVE_TARGETS.includes(ai)) throw new Error(`Unknown AI target "${ai}". Expected codex, opencode, claude, universal, or all.`);
+  if (!NATIVE_TARGETS.includes(ai)) throw new Error(`Unknown AI target "${ai}". Expected codex, opencode, cursor, claude, universal, or all.`);
   return [ai];
 }
 
@@ -35,10 +37,25 @@ export function globalSkillRootFor(target, { homeRoot = homedir() } = {}) {
   return resolve({ homeRoot });
 }
 
+export function resolveSkillRoot({ ai, scope, cwd, home = homedir() }) {
+  if (!NATIVE_TARGETS.includes(ai)) throw new Error(`Unknown AI target "${ai}".`);
+  if (scope !== 'project' && scope !== 'global') throw new Error(`Unknown scope "${scope}". Expected project or global.`);
+  if (scope === 'project') return skillRootFor(ai, cwd);
+  return globalSkillRootFor(ai, { homeRoot: home });
+}
+
+export const COMPATIBILITY_MATRIX = {
+  codex: { projectNative: true, globalNative: true },
+  opencode: { projectNative: true, globalNative: true },
+  cursor: { projectNative: true, globalNative: true },
+  claude: { projectNative: true, globalNative: true },
+  universal: { project: true, global: true },
+};
+
 export function opencodeCommandRoot(projectRoot) {
   return path.join(projectRoot, '.opencode', 'commands', 'showdar');
 }
 
 export function globalCommandRootFor({ homeRoot = homedir() } = {}) {
   return path.join(homeRoot, '.config', 'opencode', 'commands', 'showdar');
-}
+}

package/src/capabilities.js

@@ -0,0 +1,93 @@
+import { SKILLS } from './catalog.js';
+import { EVIDENCE_KEYS, INTENT_PHASES, MUTATION_CLASSES, RISK_CAPABILITIES } from './intent.js';
+
+const readOnly = ['read-only'];
+const localWrite = ['local-write'];
+const readAndLocalWrite = ['read-only', 'local-write'];
+
+// This array is the canonical capability source; SKILL.md remains the human-facing source.
+export const CAPABILITIES = Object.freeze([
+  { skill: 'showdar-understand', phases: ['discovery', 'planning'], actions: ['understand', 'investigate', 'assess'], objects: ['repository', 'architecture', 'dependency', 'api', 'data', 'runtime'], risks: [], mutations: readOnly },
+  { skill: 'showdar-requirements', phases: ['definition'], actions: ['define', 'assess', 'review'], objects: ['repository', 'backend', 'api', 'ui', 'data'], risks: [], mutations: readAndLocalWrite, evidence: { prefer: { behaviorDefined: false } } },
+  { skill: 'showdar-plan', phases: ['planning'], actions: ['plan', 'define', 'review'], objects: ['repository', 'architecture', 'backend', 'api', 'ui', 'data'], risks: [], mutations: readAndLocalWrite },
+  { skill: 'showdar-design', phases: ['design'], actions: ['design', 'review', 'modify'], objects: ['ui', 'frontend', 'mobile'], risks: [], mutations: readAndLocalWrite },
+  { skill: 'showdar-build', phases: ['implementation'], actions: ['implement', 'modify', 'fix'], objects: ['repository', 'ui', 'backend', 'api', 'data', 'runtime'], risks: ['regression', 'performance', 'data-integrity'], mutations: localWrite, evidence: { prefer: { behaviorDefined: true, rootCauseKnown: true } } },
+  { skill: 'showdar-debug', phases: ['diagnosis'], actions: ['investigate', 'reproduce', 'isolate', 'fix'], objects: ['runtime', 'build', 'network', 'state', 'auth', 'api'], risks: ['regression', 'performance', 'data-integrity'], mutations: readAndLocalWrite, evidence: { prefer: { failureObserved: true, rootCauseKnown: false }, deEmphasize: { rootCauseKnown: true } } },
+  { skill: 'showdar-test', phases: ['verification'], actions: ['test', 'review'], objects: ['repository', 'backend', 'api', 'ui', 'runtime', 'data'], risks: ['regression', 'compatibility', 'performance'], mutations: readAndLocalWrite },
+  { skill: 'showdar-quality', phases: ['verification'], actions: ['assess', 'review', 'test'], objects: ['repository', 'backend', 'api', 'ui', 'runtime'], risks: ['regression', 'compatibility'], mutations: readOnly },
+  { skill: 'showdar-review', phases: ['discovery', 'verification'], actions: ['review', 'assess'], objects: ['repository', 'architecture', 'code', 'api', 'data'], risks: ['regression'], mutations: readOnly },
+  { skill: 'showdar-security', phases: ['discovery', 'verification'], actions: ['assess', 'review'], objects: ['auth', 'secrets', 'trust-boundary', 'api', 'data'], risks: ['security'], mutations: readOnly },
+  { skill: 'showdar-upgrade', phases: ['implementation'], actions: ['upgrade', 'modify', 'test'], objects: ['dependency', 'runtime', 'backend', 'api', 'repository'], risks: ['compatibility', 'regression'], mutations: localWrite },
+  { skill: 'showdar-ship', phases: ['delivery', 'verification'], actions: ['release', 'review', 'assess'], objects: ['release', 'package', 'repository', 'deployment', 'runtime'], risks: ['production', 'compatibility'], mutations: readOnly },
+  { skill: 'showdar-ops', phases: ['operations'], actions: ['deploy', 'modify', 'assess', 'review'], objects: ['deployment', 'container', 'ci', 'runtime', 'network'], risks: ['operations', 'production'], mutations: ['local-write', 'remote-write', 'production-impacting'] },
+  { skill: 'showdar-recover', phases: ['recovery'], actions: ['recover', 'investigate'], objects: ['repository', 'implementation', 'runtime', 'state'], risks: ['data-integrity', 'regression'], mutations: readAndLocalWrite },
+  { skill: 'showdar-git', phases: ['repository'], actions: ['git', 'modify', 'review'], objects: ['repository', 'branch', 'commit'], risks: ['data-integrity', 'operations'], mutations: ['read-only', 'local-write', 'remote-write'] },
+]);
+
+const listFields = ['phases', 'actions', 'objects', 'risks', 'mutations'];
+const capabilityFields = new Set(['skill', ...listFields, 'evidence']);
+const evidenceSections = ['prefer', 'deEmphasize'];
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function validateCapabilities(definitions = CAPABILITIES, skills = SKILLS) {
+  const errors = [];
+  if (!Array.isArray(definitions)) return { ok: false, errors: ['capabilities must be an array'] };
+  const expectedSkills = new Set(skills.map(({ id }) => id));
+  const seen = new Set();
+  for (const definition of definitions) {
+    if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
+      errors.push('capability definition must be an object');
+      continue;
+    }
+    const skill = definition.skill;
+    if (typeof skill !== 'string' || !skill.trim()) {
+      errors.push('capability skill must be a non-empty string');
+      continue;
+    }
+    for (const field of Object.keys(definition)) if (!capabilityFields.has(field)) errors.push(`capability ${skill} contains unknown field: ${field}`);
+    if (!expectedSkills.has(skill)) errors.push(`capability entry for nonexistent skill: ${skill}`);
+    if (seen.has(skill)) errors.push(`capability entries contain duplicates: ${skill}`);
+    seen.add(skill);
+    for (const field of listFields) {
+      const values = definition[field];
+      if (values === undefined) continue;
+      if (!Array.isArray(values)) {
+        errors.push(`capability ${skill} ${field} must be an array`);
+        continue;
+      }
+      if (values.some((value) => typeof value !== 'string' || !value.trim())) errors.push(`capability ${skill} ${field} must contain non-empty strings`);
+      if (new Set(values).size !== values.length) errors.push(`capability ${skill} ${field} contains duplicates`);
+      const known = field === 'phases' ? new Set(INTENT_PHASES) : field === 'risks' ? new Set(RISK_CAPABILITIES) : field === 'mutations' ? new Set(MUTATION_CLASSES) : null;
+      if (known) for (const value of values) if (typeof value === 'string' && !known.has(value)) errors.push(`capability ${skill} has invalid ${field.slice(0, -1)}: ${value}`);
+    }
+    if (definition.evidence !== undefined) {
+      if (!isRecord(definition.evidence)) errors.push(`capability ${skill} evidence must be an object`);
+      else {
+        for (const section of Object.keys(definition.evidence)) {
+          if (!evidenceSections.includes(section)) {
+            errors.push(`capability ${skill} evidence has unknown section: ${section}`);
+            continue;
+          }
+          const preferences = definition.evidence[section];
+          if (!isRecord(preferences)) {
+            errors.push(`capability ${skill} evidence.${section} must be an object`);
+            continue;
+          }
+          for (const key of Object.keys(preferences)) {
+            if (!EVIDENCE_KEYS.includes(key)) errors.push(`capability ${skill} evidence.${section} has unknown key: ${key}`);
+            else if (typeof preferences[key] !== 'boolean') errors.push(`capability ${skill} evidence.${section}.${key} must be boolean`);
+          }
+        }
+      }
+    }
+  }
+  for (const skill of expectedSkills) if (!seen.has(skill)) errors.push(`missing capability entry for catalog skill: ${skill}`);
+  return { ok: errors.length === 0, errors };
+}
+
+export function getCapability(skill) {
+  return CAPABILITIES.find((definition) => definition.skill === skill) ?? null;
+}

package/src/capability-score.js

@@ -0,0 +1,82 @@
+import { CAPABILITIES, getCapability } from './capabilities.js';
+import { EVIDENCE_KEYS, normalizeIntent } from './intent.js';
+
+export const CAPABILITY_SCORE_WEIGHTS = Object.freeze({
+  phase: 4,
+  action: 3,
+  object: 2,
+  risk: 2,
+  mutation: 2,
+  evidence: 2,
+});
+
+function addUnique(list, value) {
+  if (!list.includes(value)) list.push(value);
+}
+
+function addMatch(matched, reasons, dimension, value, weight) {
+  addUnique(matched, `${dimension}:${value}`);
+  reasons.push(`matched ${dimension} ${value} (+${weight})`);
+  return weight;
+}
+
+function addMiss(unmatched, reasons, dimension, value, supported) {
+  addUnique(unmatched, `${dimension}:${value}`);
+  reasons.push(`unmatched ${dimension} ${value} (supported: ${supported.join(', ') || 'none'})`);
+}
+
+export function scoreIntent(intentInput, capability) {
+  const intent = normalizeIntent(intentInput);
+  const definition = typeof capability === 'string' ? getCapability(capability) : capability;
+  if (!definition?.skill) throw new Error('Capability with a skill id is required');
+
+  const matched = [];
+  const unmatched = [];
+  const reasons = [];
+  let score = 0;
+  // ponytail: exact labels only; add aliasing when a future router needs it.
+  const dimensions = [
+    ['phase', intent.phase, definition.phases ?? [], CAPABILITY_SCORE_WEIGHTS.phase],
+    ['action', intent.action, definition.actions ?? [], CAPABILITY_SCORE_WEIGHTS.action],
+    ['object', intent.object, definition.objects ?? [], CAPABILITY_SCORE_WEIGHTS.object],
+  ];
+  for (const [dimension, value, supported, weight] of dimensions) {
+    if (supported.includes(value)) score += addMatch(matched, reasons, dimension, value, weight);
+    else addMiss(unmatched, reasons, dimension, value, supported);
+  }
+  for (const risk of intent.risks) {
+    if ((definition.risks ?? []).includes(risk)) score += addMatch(matched, reasons, 'risk', risk, CAPABILITY_SCORE_WEIGHTS.risk);
+    else addMiss(unmatched, reasons, 'risk', risk, definition.risks ?? []);
+  }
+  if ((definition.mutations ?? []).includes(intent.mutation)) score += addMatch(matched, reasons, 'mutation', intent.mutation, CAPABILITY_SCORE_WEIGHTS.mutation);
+  else addMiss(unmatched, reasons, 'mutation', intent.mutation, definition.mutations ?? []);
+  const evidence = definition.evidence ?? {};
+  for (const section of ['prefer', 'deEmphasize']) {
+    for (const key of EVIDENCE_KEYS) {
+      const expected = evidence[section]?.[key];
+      if (expected === undefined) continue;
+      const actual = intent.evidence[key];
+      if (actual === null) {
+        reasons.push(`evidence ${key} unspecified; ${section} preference not applied`);
+      } else if (section === 'prefer' && actual === expected) {
+        score += addMatch(matched, reasons, 'evidence', `${key}=${actual}`, CAPABILITY_SCORE_WEIGHTS.evidence);
+      } else if (section === 'prefer') {
+        addMiss(unmatched, reasons, 'evidence', `${key}=${actual}`, [`${key}=${expected}`]);
+        reasons.push(`evidence mismatch ${key}: expected ${expected}, got ${actual}`);
+      } else if (actual === expected) {
+        addMiss(unmatched, reasons, 'evidence', `${key}=${actual}`, []);
+        score -= CAPABILITY_SCORE_WEIGHTS.evidence;
+        reasons.push(`evidence de-emphasized ${key}=${actual} (-${CAPABILITY_SCORE_WEIGHTS.evidence})`);
+      } else {
+        reasons.push(`evidence ${key}=${actual} did not trigger de-emphasis for ${expected}`);
+      }
+    }
+  }
+  return { skill: definition.skill, score, matched, unmatched, reasons };
+}
+
+export function rankCapabilities(intentInput, capabilities = CAPABILITIES) {
+  const intent = normalizeIntent(intentInput);
+  return capabilities.map((capability) => scoreIntent(intent, capability))
+    .sort((left, right) => right.score - left.score || (left.skill < right.skill ? -1 : left.skill > right.skill ? 1 : 0));
+}

package/src/catalog.js

@@ -16,7 +16,7 @@ export const SKILLS = [
   { id: 'showdar-ops', domain: 'ops', description: 'Use when inspecting or changing CI/CD, containers, environments, deployment, observability, rollback, or runtime operations.' },
 ];
 
-export const AI_TARGETS = ['codex', 'opencode', 'claude', 'universal', 'all'];
+export const AI_TARGETS = ['codex', 'opencode', 'cursor', 'claude', 'universal', 'all'];
 
 const ids = (...values) => values;
 
@@ -55,3 +55,16 @@ export function resolveProfile(profile) {
 export function getSkill(id) {
   return SKILLS.find((skill) => skill.id === id) ?? null;
 }
+
+export function normalizeSkillName(name) {
+  if (typeof name !== 'string' || !name.trim()) throw new Error('Skill name is required.');
+  const trimmed = name.trim();
+  const canonical = trimmed.startsWith('showdar-') ? trimmed : `showdar-${trimmed}`;
+  const skill = getSkill(canonical);
+  if (!skill) {
+    const known = SKILLS.map((s) => s.id.replace(/^showdar-/, '')).join(', ');
+    throw new Error(`Unknown skill "${name}". Available skills: ${known}`);
+  }
+  return skill.id;
+}
+