@testspectra/skills 1.1.0-rc.0

package/LICENSE.md

@@ -0,0 +1,48 @@
+# TestSpectra Commercial Software License Agreement
+
+Copyright (c) 2026 TestSpectra. All rights reserved.
+
+IMPORTANT NOTICE: This software is NOT open-source. Although distribution archives,
+npm packages, and editor extensions are publicly downloadable, installation,
+execution, and use of the Software are strictly conditioned upon obtaining a valid
+Commercial License or an authorized Evaluation/Trial License from TestSpectra.
+
+1. GRANT OF LICENSE
+   Subject to payment of applicable license fees or an active authorized evaluation
+   period, TestSpectra grants you a non-exclusive, non-transferable, revocable license
+   to install and execute the Software solely for authoring, debugging, and executing
+   automated software tests.
+
+2. LICENSE ACTIVATION & ENFORCEMENT
+   - Use of the Software requires activation via a valid License Key, authorized CI token,
+     or active TestSpectra Cloud account.
+   - Any attempt to circumvent, disable, modify, reverse engineer, or tamper with the
+     license verification mechanisms, cryptographic signatures, or binary checks is
+     a material breach of this Agreement and automatically terminates your license.
+
+3. RESTRICTIONS
+   You shall not, and shall not permit any third party to:
+   - Decompile, disassemble, reverse engineer, or derive source code from the binaries,
+     compiled scripts, or libraries of the Software.
+   - Sublicense, sell, rent, lease, distribute, or host the Software as a service for third parties.
+   - Re-brand, white-label, or package the Software or any of its components as part of a
+     competing commercial QA, testing, or developer tooling product.
+   - Modify, alter, or remove any proprietary notices, copyright labels, or license headers.
+
+4. INTELLECTUAL PROPERTY
+   The Software, including its source code, architecture, Rust core engine, algorithms,
+   matchers, extensions, interfaces, and documentation, represents valuable intellectual
+   property and trade secrets of TestSpectra.
+
+5. TERMINATION
+   This license is effective until terminated. Your rights under this license will terminate
+   automatically without notice if you fail to comply with any of its terms, or upon expiration
+   of your active subscription or trial term. Upon termination, you must cease all use of
+   the Software and delete all copies in your possession.
+
+6. DISCLAIMER OF WARRANTY & LIMITATION OF LIABILITY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+   INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+   PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   ARISING FROM THE USE OF OR INABILITY TO USE THE SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @testspectra/skills
+
+Modular AI agent skills installer & manager for standardizing **TestSpectra** script authoring —
+specs, Page Objects, shared steps, custom actions, lifecycle hooks, fixtures, and the matcher
+vocabulary.
+
+Distributed the same way as [`@testspectra/matchers`](../matchers): as a standalone npm package
+with its own CLI, installable independently of the main `@testspectra/cli`. When `@testspectra/cli`
+is already installed in a workspace, the exact same commands are also available unified under
+`spectra skills` — no separate install required.
+
+---
+
+## Quick Start
+
+```bash
+# 1. One-time setup: pick agent(s) + which skills to install, in one guided flow
+npx @testspectra/skills init          # or: spectra skills init
+
+# 2. Standalone binary (works with zero other TestSpectra packages installed)
+npx @testspectra/skills list
+npx @testspectra/skills add
+npx @testspectra/skills add workspace-structure spec-and-suite-authoring matchers-and-assertions
+npx @testspectra/skills update
+npx @testspectra/skills remove network-interception
+
+# Unified under the main CLI (equivalent — use whichever is already installed)
+spectra skills list
+spectra skills add
+spectra skills add workspace-structure spec-and-suite-authoring matchers-and-assertions
+spectra skills update
+spectra skills remove network-interception
+```
+
+`init` is a two-step guided flow:
+
+1. **Pick agent(s)** — which AI agent(s) the project uses (Claude Code, OpenCode, Kilo, Universal
+   `.agents`, or the global Gemini CLI). Saved to `.spectra-skills.json` at the workspace root, so
+   every later `list`/`add`/`update`/`remove` call reads it automatically — no need to re-detect or
+   re-specify agents each time. Without `init`, commands fall back to auto-detecting only agent
+   directories that already exist in the target workspace.
+2. **Pick skills** — a multiselect (all 8 pre-checked) of which skills to install right away for
+   the agent(s) just selected. Deselect what you don't want, or submit empty to skip installing
+   anything yet (you can always run `add` later).
+
+A one-off `--agent <ids>` (or `-a` on `spectra skills`) flag on `list`/`add`/`update`/`remove`
+overrides the saved selection for a single invocation.
+
+---
+
+## Available Skills
+
+| Skill | Covers |
+| :--- | :--- |
+| `workspace-structure` | Directory layout, zero-import architecture, file suffixes, `spectra.config.ts`, core CLI commands |
+| `spec-and-suite-authoring` | `suite.md` / `spec.md` frontmatter, the paired `*.test.ts` script, every `spectra lint` rule |
+| `page-objects-and-selectors` | Page Object pattern (`Spectra.get`/`getAll`), the `~`/`#` selector contract |
+| `matchers-and-assertions` | Full element action/assertion/collection matcher and global `Spectra.*` command reference |
+| `shared-steps-and-actions` | `Step.*` business workflows vs `support/actions/*` technical utilities |
+| `lifecycle-hooks` | `global-hooks/` vs `specs/<suite>/hooks/`, execution order, failure cascade |
+| `fixtures-data` | `fixtures/*.json` and the ambient `Fixture.*` namespace |
+| `network-interception` | `Spectra.intercept()` mocking, polling, and failure-simulation patterns |
+
+Each skill is grounded in `docs/v2/` and the reference workspace at `cli/templates/default`, so an
+AI coding agent scaffolding TestSpectra scripts produces code that already passes `spectra lint`.
+
+---
+
+## Features
+
+- **Multi-Agent, Cross-Platform**: Installs into `.claude/skills`, `.agents/skills`,
+  `.opencode/skills`, `.kilo/skills`, and the Gemini CLI's global skills directory. `init` lets you
+  pick explicitly; otherwise it auto-detects whichever the target project/agent already uses.
+- **Independent Usage**: Works in any TestSpectra workspace (default or Nx/monorepo template)
+  without requiring the main `@testspectra/cli` to be installed first.
+- **Update-in-Place**: `update` re-installs every currently-installed skill from the package's
+  current registry, so bumping `@testspectra/skills` and re-running `update` refreshes local
+  copies.

package/bin/spectra-skills.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/index.js';
+
+runCli().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/commands/add.d.ts

@@ -0,0 +1 @@
+export declare function addSkills(skillIds: string[], baseDir?: string, agentIds?: string[]): Promise<void>;

package/dist/commands/add.js

@@ -0,0 +1,44 @@
+// oxlint-disable no-console
+import { intro, outro, multiselect, isCancel, cancel } from '@clack/prompts';
+import { installSkill } from '../detector.js';
+import { loadAllSkills, getSkill } from '../registry.js';
+export async function addSkills(skillIds, baseDir = process.cwd(), agentIds) {
+    intro('\x1b[1m\x1b[36m➕ Install TestSpectra Script-Authoring Skills\x1b[0m');
+    const allSkills = loadAllSkills();
+    let targetIds = skillIds.filter(Boolean);
+    if (targetIds.length === 0) {
+        const selected = await multiselect({
+            message: 'Select TestSpectra skills to install into your AI agent environment:',
+            options: allSkills.map((s) => ({
+                value: s.id,
+                label: s.id,
+                hint: s.description,
+            })),
+            required: true,
+        });
+        if (isCancel(selected)) {
+            cancel('Operation cancelled.');
+            return;
+        }
+        targetIds = selected;
+    }
+    const installedList = [];
+    for (const id of targetIds) {
+        const skill = getSkill(id);
+        if (!skill) {
+            console.log(`\x1b[33m⚠️  Skill "${id}" not found in registry. Run "list" to view available skills.\x1b[0m`);
+            continue;
+        }
+        const paths = installSkill(skill, baseDir, agentIds);
+        installedList.push(skill.id);
+        for (const p of paths) {
+            console.log(`  \x1b[32m✔\x1b[0m Installed \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
+        }
+    }
+    if (installedList.length > 0) {
+        outro(`\x1b[32mSuccessfully installed ${installedList.length} skill(s)!\x1b[0m`);
+    }
+    else {
+        outro('No skills were installed.');
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initSkills(baseDir?: string): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,54 @@
+// oxlint-disable no-console
+import { intro, outro, multiselect, isCancel, cancel } from '@clack/prompts';
+import { KNOWN_AGENTS, writeAgentConfig, installSkill } from '../detector.js';
+import { loadAllSkills, getSkill } from '../registry.js';
+export async function initSkills(baseDir = process.cwd()) {
+    intro('\x1b[1m\x1b[36m🧭 TestSpectra Skills Setup\x1b[0m');
+    const selectedAgents = await multiselect({
+        message: 'Which AI agent(s) do you use in this project? (saved for future add/update/remove/list)',
+        options: KNOWN_AGENTS.map((a) => ({
+            value: a.id,
+            label: a.label,
+        })),
+        required: true,
+    });
+    if (isCancel(selectedAgents)) {
+        cancel('Operation cancelled.');
+        return;
+    }
+    const agentIds = selectedAgents;
+    const configPath = writeAgentConfig(baseDir, agentIds);
+    console.log(`  \x1b[32m✔\x1b[0m Saved agent selection (\x1b[1m${agentIds.join(', ')}\x1b[0m) -> \x1b[2m${configPath}\x1b[0m`);
+    const allSkills = loadAllSkills();
+    const selectedSkills = await multiselect({
+        message: 'Which skills do you want to install now for those agent(s)?',
+        options: allSkills.map((s) => ({
+            value: s.id,
+            label: s.id,
+            hint: s.description,
+        })),
+        initialValues: allSkills.map((s) => s.id),
+        required: false,
+    });
+    if (isCancel(selectedSkills)) {
+        outro('Agent selection saved. No skills installed — run `add` anytime to install skills.');
+        return;
+    }
+    const skillIds = selectedSkills;
+    if (skillIds.length === 0) {
+        outro('Agent selection saved. No skills installed — run `add` anytime to install skills.');
+        return;
+    }
+    const installedList = [];
+    for (const id of skillIds) {
+        const skill = getSkill(id);
+        if (!skill)
+            continue;
+        const paths = installSkill(skill, baseDir, agentIds);
+        installedList.push(skill.id);
+        for (const p of paths) {
+            console.log(`  \x1b[32m✔\x1b[0m Installed \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
+        }
+    }
+    outro(`\x1b[32mSetup complete!\x1b[0m Installed ${installedList.length} skill(s) for agent(s): ${agentIds.join(', ')}.`);
+}

package/dist/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function listSkills(baseDir?: string, agentIds?: string[]): void;

package/dist/commands/list.js

@@ -0,0 +1,22 @@
+// oxlint-disable no-console
+import { intro, outro } from '@clack/prompts';
+import { getAgentSkillDirs, isSkillInstalled } from '../detector.js';
+import { loadAllSkills } from '../registry.js';
+export function listSkills(baseDir = process.cwd(), agentIds) {
+    intro('\x1b[1m\x1b[36m📦 TestSpectra Skills Registry\x1b[0m');
+    const allSkills = loadAllSkills();
+    const targetDirs = getAgentSkillDirs(baseDir, agentIds);
+    if (allSkills.length === 0) {
+        console.log('No skills found in registry.');
+        outro('Done.');
+        return;
+    }
+    console.log(`\nAgent directories: \x1b[2m${targetDirs.join(', ')}\x1b[0m\n`);
+    for (const skill of allSkills) {
+        const installed = isSkillInstalled(skill.id, baseDir, agentIds);
+        const statusBadge = installed ? '\x1b[32m[Installed]\x1b[0m' : '\x1b[90m[Available]\x1b[0m';
+        console.log(`  ${statusBadge} \x1b[1m${skill.id}\x1b[0m`);
+        console.log(`    \x1b[90m${skill.description}\x1b[0m\n`);
+    }
+    outro(`Total skills: ${allSkills.length} | Run \x1b[36mnpx @testspectra/skills add <skill-name>\x1b[0m to install.`);
+}

package/dist/commands/remove.d.ts

@@ -0,0 +1 @@
+export declare function removeSkills(skillIds: string[], baseDir?: string, agentIds?: string[]): void;

package/dist/commands/remove.js

@@ -0,0 +1,26 @@
+// oxlint-disable no-console
+import { intro, outro } from '@clack/prompts';
+import { removeSkill } from '../detector.js';
+export function removeSkills(skillIds, baseDir = process.cwd(), agentIds) {
+    intro('\x1b[1m\x1b[31m🗑️  Remove TestSpectra Skills\x1b[0m');
+    const targets = skillIds.filter(Boolean);
+    if (targets.length === 0) {
+        console.log('Please specify skill name(s) to remove.');
+        outro('Aborted.');
+        return;
+    }
+    const removedList = [];
+    for (const id of targets) {
+        const paths = removeSkill(id, baseDir, agentIds);
+        if (paths.length > 0) {
+            removedList.push(id);
+            for (const p of paths) {
+                console.log(`  \x1b[31m✔\x1b[0m Removed \x1b[1m${id}\x1b[0m from \x1b[2m${p}\x1b[0m`);
+            }
+        }
+        else {
+            console.log(`  \x1b[90m- Skill "${id}" was not installed.\x1b[0m`);
+        }
+    }
+    outro(`\x1b[32mCompleted. Removed ${removedList.length} skill(s).\x1b[0m`);
+}

package/dist/commands/update.d.ts

@@ -0,0 +1 @@
+export declare function updateSkills(skillIds?: string[], baseDir?: string, agentIds?: string[]): void;

package/dist/commands/update.js

@@ -0,0 +1,30 @@
+// oxlint-disable no-console
+import { intro, outro } from '@clack/prompts';
+import { getInstalledSkills, installSkill } from '../detector.js';
+import { getSkill } from '../registry.js';
+export function updateSkills(skillIds = [], baseDir = process.cwd(), agentIds) {
+    intro('\x1b[1m\x1b[36m🔄 Update TestSpectra Skills\x1b[0m');
+    let targets = skillIds.filter(Boolean);
+    if (targets.length === 0) {
+        targets = getInstalledSkills(baseDir, agentIds);
+    }
+    if (targets.length === 0) {
+        console.log('No installed skills found in project to update.');
+        outro('Done.');
+        return;
+    }
+    const updatedList = [];
+    for (const id of targets) {
+        const skill = getSkill(id);
+        if (!skill) {
+            console.log(`\x1b[33m⚠️  Skill "${id}" not found in current registry.\x1b[0m`);
+            continue;
+        }
+        const paths = installSkill(skill, baseDir, agentIds);
+        updatedList.push(skill.id);
+        for (const p of paths) {
+            console.log(`  \x1b[32m✔\x1b[0m Updated \x1b[1m${skill.id}\x1b[0m -> \x1b[2m${p}\x1b[0m`);
+        }
+    }
+    outro(`\x1b[32mSuccessfully updated ${updatedList.length} skill(s)!\x1b[0m`);
+}

package/dist/detector.d.ts

@@ -0,0 +1,35 @@
+import type { SkillItem } from './registry.js';
+export interface AgentDefinition {
+    id: string;
+    label: string;
+    resolve: (baseDir: string) => string;
+}
+/**
+ * Every AI agent / coding assistant this package knows how to target.
+ * `resolve()` returns the absolute skills directory for that agent given a workspace baseDir.
+ */
+export declare const KNOWN_AGENTS: AgentDefinition[];
+export declare function getKnownAgentIds(): string[];
+/** Reads the agent selection persisted by `spectra-skills init`, if any. */
+export declare function readAgentConfig(baseDir?: string): string[] | undefined;
+/** Persists the agent selection chosen via `spectra-skills init` for future add/update/remove/list calls. */
+export declare function writeAgentConfig(baseDir: string, agentIds: string[]): string;
+/** Splits a comma/whitespace separated --agent value and reports any id not in KNOWN_AGENTS. */
+export declare function resolveAgentSelection(raw?: string): {
+    ids: string[];
+    unknown: string[];
+};
+/**
+ * Resolves target skill directories, in priority order:
+ *
+ * 1. `agentIds` passed explicitly (e.g. a one-off `--agent` override): resolves exactly those
+ *    agents' directories, creating them even if the agent isn't already set up in this workspace.
+ * 2. Agent selection persisted by `spectra-skills init` (`.spectra-skills.json`), if present.
+ * 3. Auto-detect: only targets agents whose directory (or its parent, e.g. `.claude`) already
+ *    exists, falling back to the universal `.agents/skills` root when nothing is detected.
+ */
+export declare function getAgentSkillDirs(baseDir?: string, agentIds?: string[]): string[];
+export declare function isSkillInstalled(skillId: string, baseDir?: string, agentIds?: string[]): boolean;
+export declare function getInstalledSkills(baseDir?: string, agentIds?: string[]): string[];
+export declare function installSkill(skill: SkillItem, baseDir?: string, agentIds?: string[]): string[];
+export declare function removeSkill(skillId: string, baseDir?: string, agentIds?: string[]): string[];

package/dist/detector.js

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Every AI agent / coding assistant this package knows how to target.
+ * `resolve()` returns the absolute skills directory for that agent given a workspace baseDir.
+ */
+export const KNOWN_AGENTS = [
+    { id: 'agents', label: 'Universal (.agents/skills)', resolve: (b) => path.join(b, '.agents', 'skills') },
+    { id: 'claude', label: 'Claude Code (.claude/skills)', resolve: (b) => path.join(b, '.claude', 'skills') },
+    { id: 'opencode', label: 'OpenCode (.opencode/skills)', resolve: (b) => path.join(b, '.opencode', 'skills') },
+    { id: 'kilo', label: 'Kilo (.kilo/skills)', resolve: (b) => path.join(b, '.kilo', 'skills') },
+    {
+        id: 'gemini',
+        label: 'Gemini CLI (~/.gemini/config/skills, global)',
+        resolve: () => path.join(os.homedir(), '.gemini', 'config', 'skills'),
+    },
+];
+export function getKnownAgentIds() {
+    return KNOWN_AGENTS.map((a) => a.id);
+}
+const CONFIG_FILENAME = '.spectra-skills.json';
+/** Reads the agent selection persisted by `spectra-skills init`, if any. */
+export function readAgentConfig(baseDir = process.cwd()) {
+    const configPath = path.join(baseDir, CONFIG_FILENAME);
+    if (!fs.existsSync(configPath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const known = new Set(getKnownAgentIds());
+        const agents = (parsed.agents ?? []).filter((id) => known.has(id));
+        return agents.length > 0 ? agents : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Persists the agent selection chosen via `spectra-skills init` for future add/update/remove/list calls. */
+export function writeAgentConfig(baseDir, agentIds) {
+    const configPath = path.join(baseDir, CONFIG_FILENAME);
+    fs.writeFileSync(configPath, JSON.stringify({ agents: agentIds }, null, 2) + '\n', 'utf-8');
+    return configPath;
+}
+/** Splits a comma/whitespace separated --agent value and reports any id not in KNOWN_AGENTS. */
+export function resolveAgentSelection(raw) {
+    if (!raw)
+        return { ids: [], unknown: [] };
+    const requested = raw
+        .split(/[,\s]+/)
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const known = new Set(getKnownAgentIds());
+    const ids = requested.filter((id) => known.has(id));
+    const unknown = requested.filter((id) => !known.has(id));
+    return { ids, unknown };
+}
+/**
+ * Resolves target skill directories, in priority order:
+ *
+ * 1. `agentIds` passed explicitly (e.g. a one-off `--agent` override): resolves exactly those
+ *    agents' directories, creating them even if the agent isn't already set up in this workspace.
+ * 2. Agent selection persisted by `spectra-skills init` (`.spectra-skills.json`), if present.
+ * 3. Auto-detect: only targets agents whose directory (or its parent, e.g. `.claude`) already
+ *    exists, falling back to the universal `.agents/skills` root when nothing is detected.
+ */
+export function getAgentSkillDirs(baseDir = process.cwd(), agentIds) {
+    const explicitOrConfigured = agentIds && agentIds.length > 0 ? agentIds : readAgentConfig(baseDir);
+    if (explicitOrConfigured && explicitOrConfigured.length > 0) {
+        const known = new Map(KNOWN_AGENTS.map((a) => [a.id, a]));
+        return explicitOrConfigured
+            .map((id) => known.get(id.toLowerCase()))
+            .filter((a) => Boolean(a))
+            .map((a) => a.resolve(baseDir));
+    }
+    const dirs = [];
+    for (const agent of KNOWN_AGENTS) {
+        const dir = agent.resolve(baseDir);
+        if (fs.existsSync(dir) || fs.existsSync(path.dirname(dir))) {
+            dirs.push(dir);
+        }
+    }
+    // No agent folder detected yet -> default to the universal agent root.
+    if (dirs.length === 0) {
+        dirs.push(path.join(baseDir, '.agents', 'skills'));
+    }
+    return dirs;
+}
+export function isSkillInstalled(skillId, baseDir = process.cwd(), agentIds) {
+    const dirs = getAgentSkillDirs(baseDir, agentIds);
+    return dirs.some((d) => fs.existsSync(path.join(d, skillId, 'SKILL.md')));
+}
+export function getInstalledSkills(baseDir = process.cwd(), agentIds) {
+    const dirs = getAgentSkillDirs(baseDir, agentIds);
+    const installed = new Set();
+    for (const d of dirs) {
+        if (!fs.existsSync(d))
+            continue;
+        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+            if (entry.isDirectory() && fs.existsSync(path.join(d, entry.name, 'SKILL.md'))) {
+                installed.add(entry.name);
+            }
+        }
+    }
+    return Array.from(installed);
+}
+export function installSkill(skill, baseDir = process.cwd(), agentIds) {
+    const targetDirs = getAgentSkillDirs(baseDir, agentIds);
+    const writtenPaths = [];
+    for (const baseSkillDir of targetDirs) {
+        const destDir = path.join(baseSkillDir, skill.id);
+        fs.mkdirSync(destDir, { recursive: true });
+        const destFile = path.join(destDir, 'SKILL.md');
+        fs.writeFileSync(destFile, skill.content, 'utf-8');
+        writtenPaths.push(destFile);
+    }
+    return writtenPaths;
+}
+export function removeSkill(skillId, baseDir = process.cwd(), agentIds) {
+    const targetDirs = getAgentSkillDirs(baseDir, agentIds);
+    const removedPaths = [];
+    for (const baseSkillDir of targetDirs) {
+        const destDir = path.join(baseSkillDir, skillId);
+        if (fs.existsSync(destDir)) {
+            fs.rmSync(destDir, { recursive: true, force: true });
+            removedPaths.push(destDir);
+        }
+    }
+    return removedPaths;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './registry.js';
+export * from './detector.js';
+export * from './commands/init.js';
+export * from './commands/list.js';
+export * from './commands/add.js';
+export * from './commands/update.js';
+export * from './commands/remove.js';
+export declare function runCli(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,119 @@
+// oxlint-disable no-console
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { initSkills } from './commands/init.js';
+import { listSkills } from './commands/list.js';
+import { addSkills } from './commands/add.js';
+import { updateSkills } from './commands/update.js';
+import { removeSkills } from './commands/remove.js';
+import { getKnownAgentIds, resolveAgentSelection } from './detector.js';
+export * from './registry.js';
+export * from './detector.js';
+export * from './commands/init.js';
+export * from './commands/list.js';
+export * from './commands/add.js';
+export * from './commands/update.js';
+export * from './commands/remove.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function getPackageVersion() {
+    try {
+        const pkgPath = path.resolve(__dirname, '../package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const HELP_TEXT = `
+\x1b[1m\x1b[36m🚀 TestSpectra Skills CLI\x1b[0m
+Install, update, and manage modular AI agent skills that standardize TestSpectra script authoring.
+
+\x1b[1mUsage:\x1b[0m
+  npx @testspectra/skills [command] [options]
+  spectra-skills [command] [options]
+
+\x1b[1mCommands:\x1b[0m
+  \x1b[36minit\x1b[0m                      Prompt which AI agent(s) you use and save the choice for future commands
+  \x1b[36mlist\x1b[0m                      List all available and installed skills
+  \x1b[36madd\x1b[0m [skills...]           Install specified skills (interactive if none provided)
+  \x1b[36mupdate\x1b[0m [skills...]        Update installed skills to latest versions
+  \x1b[36mremove\x1b[0m <skills...>        Remove specified skills from agent environment
+
+\x1b[1mOptions:\x1b[0m
+  --target <dir>             Target directory (default: current working directory)
+  --agent <ids>               One-off override: comma-separated agent(s) to target, bypassing the
+                               saved "init" selection and auto-detection. Known ids: ${getKnownAgentIds().join(', ')}
+  -h, --help                  Show help message
+  -v, --version                Show version
+
+\x1b[1mExamples:\x1b[0m
+  npx @testspectra/skills init
+  npx @testspectra/skills list
+  npx @testspectra/skills add workspace-structure
+  npx @testspectra/skills add spec-and-suite-authoring matchers-and-assertions
+  npx @testspectra/skills update
+  npx @testspectra/skills remove network-interception
+`;
+export async function runCli() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(HELP_TEXT);
+        return;
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(getPackageVersion());
+        return;
+    }
+    const parsed = parseArgs({
+        args,
+        options: {
+            target: {
+                type: 'string',
+            },
+            agent: {
+                type: 'string',
+            },
+        },
+        allowPositionals: true,
+        strict: false,
+    });
+    const baseDir = typeof parsed.values.target === 'string' ? path.resolve(parsed.values.target) : process.cwd();
+    const rawAgent = typeof parsed.values.agent === 'string' ? parsed.values.agent : undefined;
+    const { ids: agentIds, unknown: unknownAgents } = resolveAgentSelection(rawAgent);
+    if (unknownAgents.length > 0) {
+        console.log(`\x1b[33m⚠️  Unknown --agent value(s): ${unknownAgents.join(', ')}. Known ids: ${getKnownAgentIds().join(', ')}\x1b[0m`);
+    }
+    const { positionals } = parsed;
+    const command = positionals[0] || 'list';
+    const skillArgs = positionals.slice(1);
+    switch (command) {
+        case 'init':
+            await initSkills(baseDir);
+            break;
+        case 'list':
+        case 'ls':
+            listSkills(baseDir, agentIds);
+            break;
+        case 'add':
+        case 'install':
+        case 'i':
+            await addSkills(skillArgs, baseDir, agentIds);
+            break;
+        case 'update':
+        case 'up':
+            updateSkills(skillArgs, baseDir, agentIds);
+            break;
+        case 'remove':
+        case 'rm':
+        case 'delete':
+            removeSkills(skillArgs, baseDir, agentIds);
+            break;
+        default:
+            console.log(`\x1b[31mUnknown command: "${command}"\x1b[0m`);
+            console.log(HELP_TEXT);
+            process.exit(1);
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,8 @@
+export interface SkillItem {
+    id: string;
+    name: string;
+    description: string;
+    content: string;
+}
+export declare function loadAllSkills(): SkillItem[];
+export declare function getSkill(id: string): SkillItem | undefined;