@solidactions/cli 1.12.0 → 1.14.0

package/README.md

@@ -118,6 +118,24 @@ Use `solidactions <command> --help` for full flag details on any command.
 |---------|-----------|-------------|
 | `webhook list <project>` | `-e`, `--show-secrets` | List webhook URLs |
 
+### skill
+
+Manage agent skills on the crews SOP surface. `push` is an idempotent upsert (create, or update on name collision).
+
+| Command | Key Flags | Description |
+|---------|-----------|-------------|
+| `skill push <dir>` | `--role <name>`, `--dry-run`, `--json` | Push a skill folder, or a whole plugin dir — recursive: pushes every `skills/*/SKILL.md`, converts `commands/*.md` → skills, and ingests each skill's `references/`. `--role` scopes to a role instead of the shared library |
+| `skill list` | `--json`, `--limit <n>` | List skills in the library |
+| `skill view <name>` | `--json` | Show one skill |
+| `skill pull <name> [dest]` | `--json` | Fetch a skill to a local folder for editing (inverse of push) |
+| `skill delete <name>` | `--json` | Delete a skill (Admin only) |
+
+### role
+
+| Command | Key Flags | Description |
+|---------|-----------|-------------|
+| `role push <dir>` | `--dry-run`, `--json` | Push a role definition (create or update) |
+
 ### workspace
 
 | Command | Description |

package/dist/commands/role-push.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * solidactions role push <dir>
+ *
+ * Pushes a role definition to the crews library (idempotent upsert).
+ * Roles are flat peers of skills (per cli#34) — NOT nested under a role.
+ *
+ * The role def is a SKILL.md-shaped file (frontmatter name+description, body).
+ * Roles carry NO references.
+ *
+ * Supports --dry-run: pre-flight a read to detect existence; prints
+ * "[dry-run] would create/update '<name>'" without making any create/edit call.
+ *
+ * Upsert: create → on name_collision → edit.
+ * Roles use 'name' (NOT 'identifier') for read and edit.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rolePushWithConfig = rolePushWithConfig;
+exports.rolePush = rolePush;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+const skill_push_1 = require("./skill-push");
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ *
+ * Reads <dir>/SKILL.md (errors if missing), parses it via parseSkillFile,
+ * then upserts the role via the crews 'roles' MCP tool.
+ *
+ * Roles carry NO references. The 'roles' tool uses 'name' for read and edit
+ * (NOT 'identifier'). Dry-run pre-flight uses {action:'read', name}.
+ */
+async function rolePushWithConfig(dir, options, config) {
+    const absDir = path_1.default.resolve(dir);
+    // Verify the directory exists
+    if (!fs_1.default.existsSync(absDir) || !fs_1.default.statSync(absDir).isDirectory()) {
+        process.stderr.write(chalk_1.default.red(`error: "${dir}" is not a directory.\n`));
+        process.exit(1);
+    }
+    // Read and parse SKILL.md (roles use the same SKILL.md filename convention)
+    const skillMdPath = path_1.default.join(absDir, 'SKILL.md');
+    if (!fs_1.default.existsSync(skillMdPath)) {
+        process.stderr.write(chalk_1.default.red(`error: "${skillMdPath}" not found. The role directory must contain a SKILL.md file.\n`));
+        process.exit(1);
+    }
+    const skillMdContent = fs_1.default.readFileSync(skillMdPath, 'utf8');
+    let name;
+    let description;
+    let properties;
+    let body;
+    try {
+        ({ name, description, properties, body } = (0, skill_push_1.parseSkillFile)(skillMdContent));
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+        process.exit(1);
+    }
+    // --dry-run: pre-flight a read to detect existence; NO create or edit.
+    // Roles use {action:'read', name} (NOT identifier).
+    if (options.dryRun) {
+        let readResult;
+        try {
+            readResult = await (0, mcp_1.callCrewsTool)(config, 'roles', { action: 'read', name });
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+            process.exit(1);
+        }
+        if (!readResult.ok) {
+            const code = readResult.data?.code;
+            if (code === 'role_not_found') {
+                if (options.json) {
+                    console.log(JSON.stringify({}));
+                }
+                else {
+                    console.log(chalk_1.default.cyan(`[dry-run] would create '${name}'`));
+                }
+                process.exit(0);
+            }
+            // Any other error is unexpected — surface it
+            const errMsg = readResult.data?.message ?? 'MCP returned an error with no message';
+            process.stderr.write(chalk_1.default.red(`error: ${code ?? 'unknown_error'}: ${errMsg}\n`));
+            process.exit(1);
+        }
+        // Read succeeded → role exists → would update
+        if (options.json) {
+            console.log(JSON.stringify({}));
+        }
+        else {
+            console.log(chalk_1.default.cyan(`[dry-run] would update '${name}'`));
+        }
+        process.exit(0);
+    }
+    // Upsert: try create first; on name_collision switch to edit.
+    // Roles carry NO references — do not send references key.
+    let result;
+    try {
+        result = await (0, mcp_1.callCrewsTool)(config, 'roles', {
+            action: 'create',
+            name,
+            description,
+            body,
+            properties,
+        });
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+        process.exit(1);
+    }
+    // On name collision, switch to the edit path.
+    // Roles edit uses 'name' (NOT 'identifier'), and properties → properties_patch.
+    if (!result.ok && result.data?.code === 'name_collision') {
+        try {
+            result = await (0, mcp_1.callCrewsTool)(config, 'roles', {
+                action: 'edit',
+                name,
+                description,
+                body,
+                properties_patch: properties,
+            });
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+            process.exit(1);
+        }
+        if (!result.ok) {
+            const errCode = result.data?.code ?? 'unknown_error';
+            const errMsg = result.data?.message ?? 'MCP returned an error with no message';
+            process.stderr.write(chalk_1.default.red(`error: ${errCode}: ${errMsg}\n`));
+            process.exit(1);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(result.data ?? {}));
+        }
+        else {
+            console.log(chalk_1.default.green(`updated role '${name}'`));
+        }
+        process.exit(0);
+    }
+    if (!result.ok) {
+        const errCode = result.data?.code ?? 'unknown_error';
+        const errMsg = result.data?.message ?? 'MCP returned an error with no message';
+        process.stderr.write(chalk_1.default.red(`error: ${errCode}: ${errMsg}\n`));
+        process.exit(1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result.data ?? {}));
+    }
+    else {
+        const data = result.data ?? {};
+        const roleDocId = data.role_doc_id ?? data.doc_id ?? data.id ?? '?';
+        console.log(chalk_1.default.green(`created role '${name}' (doc ${roleDocId})`));
+    }
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function rolePush(dir, options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await rolePushWithConfig(dir, options, config);
+}

package/dist/commands/run-list.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runs = runs;
+exports.summaryStatusLabel = summaryStatusLabel;
+exports.detailedOutcomeTag = detailedOutcomeTag;
 const axios_1 = __importDefault(require("axios"));
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../utils/api");
@@ -70,6 +72,32 @@ async function runs(projectName, options = {}) {
     }
 }
 // ─── Display modes ─────────────────────────────────────────────────────────
+/**
+ * Summary-table status label for a run. Recovered/degraded runs share SUCCESS's
+ * execution_status, so without this they'd be indistinguishable from a clean success in
+ * the summary view. Returns the label to display and whether it's an "attention" outcome
+ * (rendered yellow). Falls back to the raw status for servers that don't send `outcome`.
+ */
+function summaryStatusLabel(run) {
+    if (run.outcome === 'recovered')
+        return { label: 'recovered', attention: true };
+    if (run.outcome === 'degraded')
+        return { label: 'degraded', attention: true };
+    return { label: run.execution_status || run.status || '?', attention: false };
+}
+/**
+ * Detailed-view tag appended to a run header ('' when none). Prefers the API `outcome`;
+ * falls back to the local hasRunErrors heuristic for servers that don't send `outcome`.
+ */
+function detailedOutcomeTag(run) {
+    if (run.outcome === 'recovered')
+        return ' [RECOVERED]';
+    if (run.outcome === 'degraded')
+        return ' [DEGRADED]';
+    if (hasRunErrors(run) && isSuccessStatus(run.execution_status || run.status || ''))
+        return ' [DEGRADED]';
+    return '';
+}
 function displaySummaryTable(runsList, projectName) {
     const header = projectName ? `Recent runs for "${projectName}":` : 'Recent runs:';
     console.log(chalk_1.default.blue(header));
@@ -79,8 +107,8 @@ function displaySummaryTable(runsList, projectName) {
     for (const run of runsList) {
         const id = String(run.id || '?').padEnd(8);
         const workflow = truncate(run.workflow_name || '?', 24).padEnd(25);
-        const status = run.execution_status || run.status || '?';
-        const statusColor = getStatusColor(status);
+        const { label: status, attention } = summaryStatusLabel(run);
+        const statusColor = attention ? chalk_1.default.yellow : getStatusColor(status);
         const triggeredAt = run.triggered_at ? new Date(run.triggered_at).toLocaleString() : '-';
         const triggeredBy = run.triggered_by || '-';
         console.log(chalk_1.default.gray(id) +
@@ -99,9 +127,9 @@ function displayDetailedList(runsList, projectName) {
         const status = run.execution_status || run.status || '?';
         const statusColor = getStatusColor(status);
         const exitStr = run.exit_code !== null && run.exit_code !== undefined ? ` (exit ${run.exit_code})` : '';
-        const isSilentFailure = hasRunErrors(run) && isSuccessStatus(status);
         console.log('');
-        const silentTag = isSilentFailure ? chalk_1.default.yellow(' [DEGRADED]') : '';
+        const outcomeTag = detailedOutcomeTag(run);
+        const silentTag = outcomeTag ? chalk_1.default.yellow(outcomeTag) : '';
         console.log(chalk_1.default.bold(`  Run #${run.id}`) + chalk_1.default.gray(` — ${run.workflow_name || '?'} (${run.project_name || '?'})`) + silentTag);
         console.log(`    Status:    ${statusColor(status)}${chalk_1.default.gray(exitStr)}`);
         console.log(`    Trigger:   ${chalk_1.default.gray(run.triggered_by || '-')}`);

package/dist/commands/skill-delete.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * solidactions skill delete <name>
+ *
+ * Deletes a skill from the crews library. Admin only.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillDeleteWithConfig = skillDeleteWithConfig;
+exports.skillDelete = skillDelete;
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ */
+async function skillDeleteWithConfig(name, options, config) {
+    let result;
+    try {
+        result = await (0, mcp_1.callCrewsTool)(config, 'skills', { action: 'delete', identifier: name });
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+        process.exit(1);
+    }
+    if (!result.ok) {
+        const code = result.data?.code ?? 'unknown_error';
+        const message = result.data?.message ?? 'MCP returned an error with no message';
+        if (code === 'permission_denied') {
+            process.stderr.write(chalk_1.default.red(`error: permission denied — deleting a skill requires Admin access.\n`));
+        }
+        else {
+            process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
+        }
+        process.exit(1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result.data));
+        process.exit(0);
+    }
+    const deleteToken = result.data?.delete_token ?? '';
+    console.log(chalk_1.default.green(`deleted skill '${name}'`) + (deleteToken ? chalk_1.default.gray(` (token: ${deleteToken})`) : ''));
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function skillDelete(name, options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await skillDeleteWithConfig(name, options, config);
+}

package/dist/commands/skill-list.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * solidactions skill list
+ *
+ * Lists skills in the crews library.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillListWithConfig = skillListWithConfig;
+exports.skillList = skillList;
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ */
+async function skillListWithConfig(options, config) {
+    const args = { action: 'list' };
+    if (options.limit !== undefined) {
+        args.limit = options.limit;
+    }
+    let result;
+    try {
+        result = await (0, mcp_1.callCrewsTool)(config, 'skills', args);
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+        process.exit(1);
+    }
+    if (!result.ok) {
+        const code = result.data?.code ?? 'unknown_error';
+        const message = result.data?.message ?? 'MCP returned an error with no message';
+        process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
+        process.exit(1);
+    }
+    const skills = result.data?.skills ?? [];
+    if (options.json) {
+        console.log(JSON.stringify(result.data));
+        process.exit(0);
+    }
+    if (skills.length === 0) {
+        console.log(chalk_1.default.gray('No skills found.'));
+        process.exit(0);
+    }
+    for (const skill of skills) {
+        const advertisedMarker = skill.catalog_advertised ? chalk_1.default.gray(' (advertised)') : '';
+        console.log(`${chalk_1.default.green(skill.name)} — ${chalk_1.default.gray(skill.description)}${advertisedMarker}`);
+    }
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function skillList(options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await skillListWithConfig(options, config);
+}

package/dist/commands/skill-pull.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * solidactions skill pull <name> [dest]
+ *
+ * Fetches a skill from the crews library and reconstructs a local skill folder
+ * (the inverse of `skill push`): writes <dest>/SKILL.md + any bundled reference
+ * files under <dest>/. Default dest = ./<name>/.
+ *
+ * --json mode: prints the raw read result from the server and exits WITHOUT
+ * writing any files. This is useful for scripting/inspection. The default
+ * (no --json) writes the folder.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillPullWithConfig = skillPullWithConfig;
+exports.skillPull = skillPull;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ *
+ * Steps:
+ *  1. Call skills.read to fetch the skill from the library.
+ *  2. If --json: print the raw result, exit 0 (no file writes).
+ *  3. Otherwise: reconstruct SKILL.md from the returned `properties` (which
+ *     contains name, description, and any extra props), OMITTING `type` (the
+ *     server sets it; stripping mirrors what parseSkillFile does on push so a
+ *     push→pull→push round-trip is idempotent). Write <dest>/SKILL.md, then
+ *     write each reference file under <dest>/ with a path-traversal guard.
+ */
+async function skillPullWithConfig(name, dest, options, config) {
+    // Call the crews MCP server for a skills.read
+    let result;
+    try {
+        result = await (0, mcp_1.callCrewsTool)(config, 'skills', { action: 'read', identifier: name });
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+        process.exit(1);
+    }
+    if (!result.ok) {
+        const code = result.data?.code ?? 'unknown_error';
+        const message = result.data?.message ?? 'MCP returned an error with no message';
+        process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
+        process.exit(1);
+    }
+    const data = result.data;
+    // --json mode: print raw result and exit WITHOUT writing files.
+    // This is intentionally non-destructive: inspect the raw server payload
+    // without side-effects. File reconstruction is the default (no --json) mode.
+    if (options.json) {
+        console.log(JSON.stringify(data));
+        process.exit(0);
+    }
+    // Resolve the output directory (default: ./<name>/)
+    const out = dest ?? './' + name;
+    const absOut = path_1.default.resolve(out);
+    // Build the frontmatter object from `properties`, OMITTING `type`.
+    // The server stores a `type` field but it is stripped on push (parseSkillFile
+    // does `const { type: _type, ...properties } = rest`). We mirror that here
+    // so that pull → push is idempotent.
+    const { type: _type, name: propName, description: propDescription, ...extraProps } = data.properties;
+    // Reconstruct the full frontmatter: name + description (from properties)
+    // followed by all remaining extra props (minus type).
+    const frontmatterObj = {
+        name: propName,
+        description: propDescription,
+        ...extraProps,
+    };
+    // yaml.dump produces "key: value\n" lines; we wrap in ---\n...\n---\n
+    const yamlBlock = js_yaml_1.default.dump(frontmatterObj, { lineWidth: -1 });
+    const body = data.body ?? '';
+    // Ensure the body starts on its own line after the closing ---
+    const skillMdContent = `---\n${yamlBlock}---\n${body.startsWith('\n') ? body : '\n' + body}`;
+    // Create the output directory (and parents) if needed
+    fs_1.default.mkdirSync(absOut, { recursive: true });
+    // Write SKILL.md
+    fs_1.default.writeFileSync(path_1.default.join(absOut, 'SKILL.md'), skillMdContent, 'utf8');
+    // Write reference files, guarding against path traversal
+    const reference = data.reference ?? {};
+    const absOutNorm = path_1.default.resolve(absOut) + path_1.default.sep;
+    let writtenCount = 0;
+    let skippedCount = 0;
+    for (const [key, content] of Object.entries(reference)) {
+        // Guard 1: reject absolute paths
+        if (path_1.default.isAbsolute(key)) {
+            process.stderr.write(chalk_1.default.yellow(`warn: skipping unsafe reference key (absolute path): ${key}\n`));
+            skippedCount++;
+            continue;
+        }
+        // Guard 2: reject path traversal (any key that resolves outside absOut)
+        const target = path_1.default.resolve(absOut, key);
+        if (!target.startsWith(absOutNorm)) {
+            process.stderr.write(chalk_1.default.yellow(`warn: skipping unsafe reference key (traversal): ${key}\n`));
+            skippedCount++;
+            continue;
+        }
+        // Safe: create parent dirs and write the file
+        fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+        fs_1.default.writeFileSync(target, content, 'utf8');
+        writtenCount++;
+    }
+    const refSummary = writtenCount === 1 ? '1 reference' : `${writtenCount} references`;
+    console.log(chalk_1.default.green(`pulled skill '${name}' → ${out} (${refSummary})`));
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function skillPull(name, dest, options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await skillPullWithConfig(name, dest, options, config);
+}

package/dist/commands/skill-push.js

@@ -4,13 +4,20 @@
  *
  * Pushes a local skill folder into the crews library via the crews MCP server.
  * Idempotent upsert: create, or update on name collision.
+ *
+ * Supports two modes:
+ *   - Single-skill: <dir>/SKILL.md exists → push that one skill.
+ *   - Plugin: <dir>/skills/<name>/SKILL.md and/or <dir>/commands/<name>.md → push all.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseSkillFile = parseSkillFile;
-exports.readTopLevelReferences = readTopLevelReferences;
+exports.readReferences = readReferences;
+exports.readSkillDir = readSkillDir;
+exports.parseCommandFile = parseCommandFile;
+exports.pushParsedSkill = pushParsedSkill;
 exports.skillPushWithConfig = skillPushWithConfig;
 exports.skillPush = skillPush;
 const fs_1 = __importDefault(require("fs"));
@@ -65,55 +72,141 @@ function parseSkillFile(content) {
     return { name, description, properties, body };
 }
 /**
- * Read top-level (non-recursive) files in dir, excluding SKILL.md.
- * Returns a map of filename → utf8 contents.
+ * Recursively read every bundled file under a skill dir, excluding the
+ * top-level SKILL.md. Returns a map of reference-key → utf8 contents.
+ *
+ * Keys are the file's POSIX path relative to the skill dir: top-level files
+ * keep a bare-filename key (e.g. "helper.py"), and files in subfolders keep
+ * their relative path (e.g. "references/member-roles.md") — matching how
+ * SKILL.md cites them, so bundled reference docs land complete (#247).
  */
-function readTopLevelReferences(dir) {
-    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+function readReferences(dir) {
     const references = {};
-    for (const entry of entries) {
-        if (!entry.isFile())
-            continue;
-        if (entry.name === 'SKILL.md')
-            continue;
-        const filePath = path_1.default.join(dir, entry.name);
-        references[entry.name] = fs_1.default.readFileSync(filePath, 'utf8');
-    }
+    const walk = (current) => {
+        for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
+            const abs = path_1.default.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            // POSIX-normalised path relative to the skill dir, used as the key.
+            const key = path_1.default.relative(dir, abs).split(path_1.default.sep).join('/');
+            if (key === 'SKILL.md')
+                continue; // exclude only the top-level skill file
+            references[key] = fs_1.default.readFileSync(abs, 'utf8');
+        }
+    };
+    walk(dir);
     return references;
 }
 /**
- * Core implementation — accepts an injected config so tests can point at a
- * stub server without touching the filesystem config.
+ * Read a skill directory: validates the dir exists, reads SKILL.md, parses it,
+ * and reads bundled reference files. Returns the full payload for pushParsedSkill.
+ *
+ * Throws with a descriptive message on any filesystem or parse error.
  */
-async function skillPushWithConfig(dir, options, config) {
+function readSkillDir(dir) {
     const absDir = path_1.default.resolve(dir);
-    // 1. Check directory exists
     if (!fs_1.default.existsSync(absDir) || !fs_1.default.statSync(absDir).isDirectory()) {
-        process.stderr.write(chalk_1.default.red(`error: "${dir}" is not a directory.\n`));
-        process.exit(1);
+        throw new Error(`"${dir}" is not a directory.`);
     }
-    // 2. Read SKILL.md
     const skillMdPath = path_1.default.join(absDir, 'SKILL.md');
     if (!fs_1.default.existsSync(skillMdPath)) {
-        process.stderr.write(chalk_1.default.red(`error: "${skillMdPath}" not found. The skill directory must contain a SKILL.md file.\n`));
-        process.exit(1);
+        throw new Error(`"${skillMdPath}" not found. The skill directory must contain a SKILL.md file.`);
     }
     const skillMdContent = fs_1.default.readFileSync(skillMdPath, 'utf8');
-    // 3. Parse frontmatter + body
-    let parsed;
+    const { name, description, properties, body } = parseSkillFile(skillMdContent);
+    const references = readReferences(absDir);
+    return { name, description, properties, body, references };
+}
+/**
+ * Parse a commands/<name>.md file (plugin command format).
+ *
+ * Derives the skill name from the filename (kebab-case: lowercase, spaces and
+ * underscores replaced with hyphens). The frontmatter must contain `description`;
+ * `name`, `allowed-tools`, and `argument-hint` are not carried forward.
+ *
+ * Returns a SkillPayload with properties={} and references={}.
+ * Throws with a descriptive message if description is missing or frontmatter malformed.
+ */
+function parseCommandFile(filename, content) {
+    // Derive name from filename (basename without extension, converted to kebab-case)
+    const base = path_1.default.basename(filename, '.md');
+    const name = base.toLowerCase().replace(/[\s_]+/g, '-');
+    if (!content.startsWith('---')) {
+        throw new Error(`${filename}: command file must begin with a YAML frontmatter block (---).`);
+    }
+    const afterOpen = content.slice(3);
+    const closeIdx = afterOpen.indexOf('\n---');
+    if (closeIdx === -1) {
+        throw new Error(`${filename}: command file frontmatter is not closed (missing closing ---).`);
+    }
+    const yamlBlock = afterOpen.slice(0, closeIdx);
+    const body = afterOpen.slice(closeIdx + 4).replace(/^\n/, '');
+    let fm;
     try {
-        parsed = parseSkillFile(skillMdContent);
+        fm = js_yaml_1.default.load(yamlBlock);
     }
     catch (e) {
-        process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
-        process.exit(1);
+        throw new Error(`${filename}: failed to parse command file frontmatter YAML: ${e.message}`);
+    }
+    if (!fm || typeof fm !== 'object') {
+        throw new Error(`${filename}: command file frontmatter is empty or not a YAML object.`);
+    }
+    if (!fm.description || typeof fm.description !== 'string') {
+        throw new Error(`${filename}: command file frontmatter must contain a "description" field (string).`);
     }
-    const { name, description, properties, body } = parsed;
-    // 4. Read sibling reference files
-    const references = readTopLevelReferences(absDir);
-    // 5. Compose an idempotent upsert: try create; on name_collision, edit.
+    return {
+        name,
+        description: fm.description,
+        properties: {},
+        body,
+        references: {},
+    };
+}
+/**
+ * Core upsert: try create; on name_collision, switch to edit.
+ * Returns a result object — does NOT call process.exit and does NOT print.
+ * Throws on non-collision MCP errors.
+ *
+ * When options.dryRun is true, performs only a skills.read pre-flight and
+ * returns {status:'would-create'} or {status:'would-update'} without any
+ * create or edit call.
+ */
+async function pushParsedSkill(payload, options, config) {
+    const { name, description, properties, body, references } = payload;
     const isRole = !!options.role;
     const tool = isRole ? 'roles' : 'skills';
+    // --dry-run: pre-flight a read to detect existence; make NO create/edit calls.
+    if (options.dryRun) {
+        // Role-scoped skills are read via the roles tool's read_skill {role, name};
+        // shared skills via the skills tool's read {identifier}. Both return
+        // `skill_not_found` when absent. (read does NOT accept `identifier` on the
+        // roles tool, so the action/args must branch on isRole.)
+        const readArgs = isRole
+            ? { action: 'read_skill', role: options.role, name }
+            : { action: 'read', identifier: name };
+        let readResult;
+        try {
+            readResult = await (0, mcp_1.callCrewsTool)(config, tool, readArgs);
+        }
+        catch (e) {
+            throw new Error(`MCP request failed — ${e.message}`);
+        }
+        if (!readResult.ok) {
+            const code = readResult.data?.code;
+            if (code === 'skill_not_found') {
+                return { status: 'would-create', name, data: {} };
+            }
+            // Any other error is unexpected — surface it
+            const errMsg = readResult.data?.message ?? 'MCP returned an error with no message';
+            throw new Error(`${code ?? 'unknown_error'}: ${errMsg}`);
+        }
+        // Read succeeded → skill exists → would update
+        return { status: 'would-update', name, data: {} };
+    }
     const createArgs = isRole
         ? { action: 'create_skill', role: options.role, name, description, body, properties, references }
         : { action: 'create', name, description, body, properties, references };
@@ -122,11 +215,9 @@ async function skillPushWithConfig(dir, options, config) {
         result = await (0, mcp_1.callCrewsTool)(config, tool, createArgs);
     }
     catch (e) {
-        process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
-        process.exit(1);
+        throw new Error(`MCP request failed — ${e.message}`);
     }
-    let didUpdate = false;
-    // 6. On name collision, switch to the edit path (the upsert). properties → properties_patch.
+    // On name collision, switch to the edit path. properties → properties_patch.
     if (!result.ok && result.data?.code === 'name_collision') {
         const editArgs = isRole
             ? { action: 'edit_skill', role: options.role, name, description, body, properties_patch: properties, references }
@@ -135,34 +226,186 @@ async function skillPushWithConfig(dir, options, config) {
             result = await (0, mcp_1.callCrewsTool)(config, tool, editArgs);
         }
         catch (e) {
-            process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
-            process.exit(1);
+            throw new Error(`MCP request failed — ${e.message}`);
         }
-        didUpdate = true;
+        if (!result.ok) {
+            const errData = result.data;
+            const errCode = errData?.code ?? 'unknown_error';
+            const errMsg = errData?.message ?? 'MCP returned an error with no message';
+            throw new Error(`${errCode}: ${errMsg}`);
+        }
+        return { status: 'updated', name, data: result.data ?? {} };
     }
-    // 7. Handle result.
     if (!result.ok) {
         const errData = result.data;
         const errCode = errData?.code ?? 'unknown_error';
         const errMsg = errData?.message ?? 'MCP returned an error with no message';
-        process.stderr.write(chalk_1.default.red(`${errCode}: ${errMsg}\n`));
-        process.exit(1);
+        throw new Error(`${errCode}: ${errMsg}`);
     }
+    return { status: 'created', name, data: result.data ?? {} };
+}
+/**
+ * Print a single skill push result line (shared between single and plugin modes).
+ */
+function printPushResult(result, options) {
     if (options.json) {
         console.log(JSON.stringify(result.data));
-        process.exit(0);
+        return;
     }
-    const data = result.data;
-    if (didUpdate) {
-        // edit shape: {version_id, body_blob_sha}
+    const { status, name, data } = result;
+    if (status === 'would-create') {
+        console.log(chalk_1.default.cyan(`[dry-run] would create '${name}'`));
+    }
+    else if (status === 'would-update') {
+        console.log(chalk_1.default.cyan(`[dry-run] would update '${name}'`));
+    }
+    else if (status === 'updated') {
         console.log(chalk_1.default.green(`updated skill '${name}' (version ${data.version_id ?? '?'})`));
     }
     else {
-        // create shape: {skill_doc_id, folder_id, reference_doc_ids}
         const skillDocId = data.skill_doc_id ?? data.doc_id ?? data.id ?? '?';
         const refCount = Object.keys(data.reference_doc_ids ?? {}).length;
         console.log(chalk_1.default.green(`created skill '${name}' (doc ${skillDocId}, ${refCount} refs)`));
     }
+}
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ *
+ * Routes between single-skill mode (top-level SKILL.md) and plugin mode
+ * (skills/ + commands/ subdirectories) based on directory structure.
+ */
+async function skillPushWithConfig(dir, options, config) {
+    const absDir = path_1.default.resolve(dir);
+    if (!fs_1.default.existsSync(absDir) || !fs_1.default.statSync(absDir).isDirectory()) {
+        process.stderr.write(chalk_1.default.red(`error: "${dir}" is not a directory.\n`));
+        process.exit(1);
+    }
+    const topLevelSkillMd = path_1.default.join(absDir, 'SKILL.md');
+    // -------------------------------------------------------------------------
+    // Single-skill mode: <dir>/SKILL.md exists
+    // -------------------------------------------------------------------------
+    if (fs_1.default.existsSync(topLevelSkillMd)) {
+        let payload;
+        try {
+            payload = readSkillDir(dir);
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+            process.exit(1);
+        }
+        let pushResult;
+        try {
+            pushResult = await pushParsedSkill(payload, options, config);
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+            process.exit(1);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(pushResult.data));
+        }
+        else {
+            printPushResult(pushResult, options);
+        }
+        process.exit(0);
+    }
+    // -------------------------------------------------------------------------
+    // Plugin mode: push skills/<name>/SKILL.md + commands/<name>.md
+    // -------------------------------------------------------------------------
+    const payloads = [];
+    // One-level glob: skills/*/SKILL.md
+    const skillsDir = path_1.default.join(absDir, 'skills');
+    if (fs_1.default.existsSync(skillsDir) && fs_1.default.statSync(skillsDir).isDirectory()) {
+        for (const entry of fs_1.default.readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const skillSubdir = path_1.default.join(skillsDir, entry.name);
+            const skillMd = path_1.default.join(skillSubdir, 'SKILL.md');
+            if (!fs_1.default.existsSync(skillMd))
+                continue;
+            try {
+                payloads.push(readSkillDir(skillSubdir));
+            }
+            catch (e) {
+                process.stderr.write(chalk_1.default.red(`error: skills/${entry.name}/SKILL.md: ${e.message}\n`));
+                process.exit(1);
+            }
+        }
+    }
+    // One-level glob: commands/*.md
+    const commandsDir = path_1.default.join(absDir, 'commands');
+    if (fs_1.default.existsSync(commandsDir) && fs_1.default.statSync(commandsDir).isDirectory()) {
+        for (const entry of fs_1.default.readdirSync(commandsDir, { withFileTypes: true })) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.md'))
+                continue;
+            const cmdPath = path_1.default.join(commandsDir, entry.name);
+            const content = fs_1.default.readFileSync(cmdPath, 'utf8');
+            try {
+                payloads.push(parseCommandFile(entry.name, content));
+            }
+            catch (e) {
+                process.stderr.write(chalk_1.default.red(`error: commands/${entry.name}: ${e.message}\n`));
+                process.exit(1);
+            }
+        }
+    }
+    if (payloads.length === 0) {
+        process.stderr.write(chalk_1.default.red(`error: no skills/ or commands/ under "${dir}" — nothing to push.\n`));
+        process.exit(1);
+    }
+    // Detect duplicate names BEFORE any push
+    const seen = new Map();
+    for (const p of payloads) {
+        seen.set(p.name, (seen.get(p.name) ?? 0) + 1);
+    }
+    const conflicts = [...seen.entries()].filter(([, count]) => count > 1).map(([name]) => name);
+    if (conflicts.length > 0) {
+        process.stderr.write(chalk_1.default.red(`error: duplicate skill names detected — aborting before any push.\n`) +
+            chalk_1.default.red(`  conflicts: ${conflicts.join(', ')}\n`) +
+            chalk_1.default.red(`  Rename the conflicting skills/commands so all names are unique.\n`));
+        process.exit(1);
+    }
+    // Push each skill, print a summary line per item
+    let createdCount = 0;
+    let updatedCount = 0;
+    for (const payload of payloads) {
+        let pushResult;
+        try {
+            pushResult = await pushParsedSkill(payload, options, config);
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: ${payload.name}: ${e.message}\n`));
+            process.exit(1);
+        }
+        printPushResult(pushResult, options);
+        if (pushResult.status === 'created' || pushResult.status === 'would-create') {
+            createdCount++;
+        }
+        else {
+            updatedCount++;
+        }
+    }
+    // Final tally
+    if (!options.json) {
+        const parts = [];
+        if (options.dryRun) {
+            if (createdCount > 0)
+                parts.push(`${createdCount} would create`);
+            if (updatedCount > 0)
+                parts.push(`${updatedCount} would update`);
+            console.log(chalk_1.default.cyan(`\n[dry-run] ${payloads.length} skill(s) (${parts.join(', ')})`));
+        }
+        else {
+            if (createdCount > 0)
+                parts.push(`${createdCount} created`);
+            if (updatedCount > 0)
+                parts.push(`${updatedCount} updated`);
+            console.log(chalk_1.default.cyan(`\ndone: ${payloads.length} skill(s) pushed (${parts.join(', ')})`));
+        }
+    }
     process.exit(0);
 }
 /**

package/dist/commands/skill-view.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * solidactions skill view <name>
+ *
+ * Shows the full details of a single skill from the crews library.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillViewWithConfig = skillViewWithConfig;
+exports.skillView = skillView;
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ */
+async function skillViewWithConfig(name, options, config) {
+    let result;
+    try {
+        result = await (0, mcp_1.callCrewsTool)(config, 'skills', { action: 'read', identifier: name });
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+        process.exit(1);
+    }
+    if (!result.ok) {
+        const code = result.data?.code ?? 'unknown_error';
+        const message = result.data?.message ?? 'MCP returned an error with no message';
+        process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
+        process.exit(1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result.data));
+        process.exit(0);
+    }
+    const data = result.data ?? {};
+    const identifier = data.identifier ?? name;
+    const description = data.properties?.description ?? '';
+    const body = data.body ?? '';
+    console.log(chalk_1.default.green(identifier));
+    if (description) {
+        console.log(chalk_1.default.gray(description));
+    }
+    if (body) {
+        console.log('');
+        console.log(body);
+    }
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function skillView(name, options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await skillViewWithConfig(name, options, config);
+}

package/dist/index.js

@@ -33,6 +33,11 @@ const oauth_actions_list_1 = require("./commands/oauth-actions-list");
 const oauth_actions_show_1 = require("./commands/oauth-actions-show");
 const workspaces_1 = require("./commands/workspaces");
 const skill_push_1 = require("./commands/skill-push");
+const skill_pull_1 = require("./commands/skill-pull");
+const skill_list_1 = require("./commands/skill-list");
+const skill_view_1 = require("./commands/skill-view");
+const skill_delete_1 = require("./commands/skill-delete");
+const role_push_1 = require("./commands/role-push");
 const config_1 = require("./utils/config");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
@@ -402,9 +407,53 @@ skill
     .argument('<dir>', 'Path to the skill directory (must contain SKILL.md)')
     .option('--role <name>', 'Scope the skill to a role instead of the shared library')
     .option('--json', 'Output result as JSON')
+    .option('--dry-run', 'Preview create vs update without writing')
     .action(async (dir, options) => {
     await (0, skill_push_1.skillPush)(dir, options);
 });
+skill
+    .command('pull')
+    .description('Fetch a skill from the library to a local folder for editing (inverse of push)')
+    .argument('<name>', 'Skill name or identifier')
+    .argument('[dest]', 'Destination directory (defaults to ./<name>/)')
+    .option('--json', 'Output raw read result as JSON (no file writes)')
+    .action(async (name, dest, options) => {
+    await (0, skill_pull_1.skillPull)(name, dest, options);
+});
+skill
+    .command('list')
+    .description('List skills in the library')
+    .option('--json', 'Output as JSON')
+    .option('--limit <n>', 'Maximum number of skills to return', (v) => parseInt(v, 10))
+    .action(async (options) => {
+    await (0, skill_list_1.skillList)(options);
+});
+skill
+    .command('view <name>')
+    .description('Show one skill')
+    .option('--json', 'Output as JSON')
+    .action(async (name, options) => {
+    await (0, skill_view_1.skillView)(name, options);
+});
+skill
+    .command('delete <name>')
+    .description('Delete a skill (Admin only)')
+    .option('--json', 'Output as JSON')
+    .action(async (name, options) => {
+    await (0, skill_delete_1.skillDelete)(name, options);
+});
+// =============================================================================
+// role <subcommand>  (SOP surface — flat peer of skill, per cli#34)
+// =============================================================================
+const role = program.command('role').description('Manage roles (crews SOP surface)');
+role
+    .command('push <dir>')
+    .description('Push a role definition (create or update)')
+    .option('--dry-run', 'Preview create vs update without writing')
+    .option('--json', 'Output result as JSON')
+    .action(async (dir, options) => {
+    await (0, role_push_1.rolePush)(dir, options);
+});
 program.parseAsync().catch((err) => {
     console.error(chalk_1.default.red(err.message ?? String(err)));
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidactions/cli",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "SolidActions CLI - Deploy and manage workflow automation",
   "main": "dist/index.js",
   "bin": {