@sweny-ai/core 0.1.87 → 0.1.89

package/dist/cli/main.js

@@ -30,6 +30,7 @@ import { c, formatBanner, getStepDetails, formatStepLine, formatDagResultHuman,
 import { checkProviderConnectivity } from "./check.js";
 import { registerSetupCommand } from "./setup.js";
 import { registerPublishCommand } from "./publish.js";
+import { registerSkillCommand } from "./skill.js";
 import { reportToCloud } from "./cloud-report.js";
 import { runUpgrade, fetchLatestFromNpm } from "./upgrade.js";
 import { maybeNudge, defaultCachePath } from "./version-check.js";
@@ -101,6 +102,7 @@ program
 });
 registerSetupCommand(program);
 registerPublishCommand(program);
+registerSkillCommand(program);
 // ── Credential map builder ──────────────────────────────────────────
 // buildCredentialMap lives in ./credentials.ts so tests can import it
 // without triggering main.ts's top-level program.parse() side effect.
@@ -601,15 +603,21 @@ export async function workflowRunAction(file, options) {
         console.error(chalk.red(`\n  Workflow cannot run — missing required skills:\n`));
         for (const err of validation.errors)
             console.error(chalk.red(`    \u2717 ${err}`));
-        if (validation.missing.length > 0) {
-            console.error(chalk.dim(`\n  Set the missing env vars and try again:`));
-            for (const m of validation.missing) {
-                if (m.missingEnv.length > 0) {
-                    console.error(chalk.dim(`    - ${m.id}: ${m.missingEnv.join(", ")}`));
-                }
+        const unknown = validation.missing.filter((m) => m.category === "unknown");
+        const envGaps = validation.missing.filter((m) => m.category !== "unknown" && m.missingEnv.length > 0);
+        if (unknown.length > 0) {
+            console.error(chalk.dim(`\n  These skill IDs aren't built-in or discovered in .{claude,sweny,agents,gemini}/skills/.\n  Scaffold one with:\n`));
+            for (const m of unknown) {
+                console.error(chalk.dim(`    sweny skill new ${m.id}`));
+            }
+        }
+        if (envGaps.length > 0) {
+            console.error(chalk.dim(`\n  These skills are built-in but their env vars aren't set:`));
+            for (const m of envGaps) {
+                console.error(chalk.dim(`    - ${m.id}: ${m.missingEnv.join(", ")}`));
             }
         }
-        console.error("");
+        console.error(chalk.dim(`\n  Run \`sweny skill list\` to see what's available.\n`));
         process.exit(1);
         return;
     }

package/dist/cli/skill.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `sweny skill` command group — discover, list, and scaffold skills.
+ *
+ * Skills are the unit of capability a workflow node names in its `skills`
+ * array. Sweny ships built-ins (github, linear, slack, ...) and discovers
+ * custom skills from `.{gemini,agents,claude,sweny}/skills/<id>/SKILL.md`.
+ *
+ * This module owns the *authoring* side of that loop:
+ *
+ *   sweny skill new <id>     scaffold a SKILL.md template
+ *   sweny skill list         list built-in + custom skills together
+ *
+ * Discovery and validation already live in `../skills/custom-loader.js`
+ * and `../skills/index.js`; this CLI is a thin authoring shell over them.
+ */
+import { Command } from "commander";
+import { type SkillCategory } from "../types.js";
+declare const HARNESS_DIRS: {
+    readonly claude: ".claude/skills";
+    readonly sweny: ".sweny/skills";
+    readonly agents: ".agents/skills";
+    readonly gemini: ".gemini/skills";
+};
+type HarnessKey = keyof typeof HARNESS_DIRS;
+/** Build the SKILL.md body for a fresh scaffold. Exported for tests. */
+export declare function renderSkillTemplate(opts: {
+    id: string;
+    description: string;
+    category: SkillCategory;
+}): string;
+interface NewOptions {
+    description?: string;
+    category?: string;
+    harness?: HarnessKey;
+    force?: boolean;
+}
+/**
+ * Action handler for `sweny skill new`. Exported for unit tests; production
+ * code goes through `registerSkillCommand`. `cwd` defaults to `process.cwd()`
+ * so the CLI works as expected; tests pass a tmp dir for isolation.
+ */
+export declare function runSkillNew(idArg: string, options: NewOptions, cwd?: string): void;
+interface ListOptions {
+    json?: boolean;
+}
+/**
+ * Action handler for `sweny skill list`. Exported for unit tests; production
+ * code goes through `registerSkillCommand`. `cwd` and `env` injection lets
+ * tests exercise the configured-badge logic without polluting global state.
+ */
+export declare function runSkillList(options: ListOptions, cwd?: string, env?: Record<string, string | undefined>): void;
+/** Register the `sweny skill` subcommand group on the parent program. */
+export declare function registerSkillCommand(program: Command): void;
+export {};

package/dist/cli/skill.js

@@ -0,0 +1,208 @@
+/**
+ * `sweny skill` command group — discover, list, and scaffold skills.
+ *
+ * Skills are the unit of capability a workflow node names in its `skills`
+ * array. Sweny ships built-ins (github, linear, slack, ...) and discovers
+ * custom skills from `.{gemini,agents,claude,sweny}/skills/<id>/SKILL.md`.
+ *
+ * This module owns the *authoring* side of that loop:
+ *
+ *   sweny skill new <id>     scaffold a SKILL.md template
+ *   sweny skill list         list built-in + custom skills together
+ *
+ * Discovery and validation already live in `../skills/custom-loader.js`
+ * and `../skills/index.js`; this CLI is a thin authoring shell over them.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import chalk from "chalk";
+import { builtinSkills } from "../skills/index.js";
+import { configuredSkillsWithDiagnostics, discoverSkillsWithDiagnostics } from "../skills/custom-loader.js";
+import { SKILL_CATEGORIES } from "../types.js";
+// Mirror of the loader's regex so authoring-side validation matches discovery.
+const VALID_SKILL_ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const HARNESS_DIRS = {
+    claude: ".claude/skills",
+    sweny: ".sweny/skills",
+    agents: ".agents/skills",
+    gemini: ".gemini/skills",
+};
+/** Build the SKILL.md body for a fresh scaffold. Exported for tests. */
+export function renderSkillTemplate(opts) {
+    const { id, description, category } = opts;
+    const lines = [];
+    lines.push("---");
+    lines.push(`name: ${id}`);
+    lines.push(`description: ${description}`);
+    lines.push(`category: ${category}`);
+    lines.push("# config:");
+    lines.push("#   EXAMPLE_ENV_VAR:");
+    lines.push("#     description: Human-readable description shown by `sweny check`");
+    lines.push("#     required: true");
+    lines.push("# mcp:");
+    lines.push("#   command: npx");
+    lines.push('#   args: ["-y", "@your-org/your-mcp-server"]');
+    lines.push("#   env:");
+    lines.push("#     SOMETHING: ${SOMETHING}");
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${id}`);
+    lines.push("");
+    lines.push(description);
+    lines.push("");
+    lines.push("## When to use");
+    lines.push("");
+    lines.push(`Reference this skill from a workflow node when the node needs ${description.toLowerCase()}.`);
+    lines.push("");
+    lines.push("```yaml");
+    lines.push("nodes:");
+    lines.push("  my_node:");
+    lines.push("    name: My Node");
+    lines.push(`    instruction: >-`);
+    lines.push(`      Use the ${id} capability described in this skill.`);
+    lines.push(`    skills: [${id}]`);
+    lines.push("```");
+    lines.push("");
+    lines.push("## What this skill provides");
+    lines.push("");
+    lines.push("Describe the contract this skill exposes. Custom skills are *instruction-only* by default — the markdown body becomes guidance the LLM sees when the node runs. Add an `mcp:` block in the frontmatter above to wire in tool execution via an MCP server.");
+    lines.push("");
+    lines.push("Concrete things to document here:");
+    lines.push("");
+    lines.push("- Required environment variables (also declare in `config:` above so `sweny check` validates them).");
+    lines.push("- The exact commands or tool calls the node should make.");
+    lines.push("- Common failure modes and how to recover.");
+    lines.push("- Any preconditions the workflow must satisfy before invoking this skill.");
+    lines.push("");
+    lines.push("## Example invocation");
+    lines.push("");
+    lines.push("Replace this section with a concrete usage example, including the exact bash, MCP tool call, or LLM prompt the node should produce.");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Action handler for `sweny skill new`. Exported for unit tests; production
+ * code goes through `registerSkillCommand`. `cwd` defaults to `process.cwd()`
+ * so the CLI works as expected; tests pass a tmp dir for isolation.
+ */
+export function runSkillNew(idArg, options, cwd = process.cwd()) {
+    const id = idArg.toLowerCase();
+    if (!VALID_SKILL_ID.test(id) || id.includes("--") || id.length > 64) {
+        console.error(chalk.red(`  Invalid skill id "${idArg}".\n  Skill ids must be lowercase alphanumeric + hyphens (no consecutive hyphens), max 64 chars.`));
+        process.exit(2);
+        return;
+    }
+    const description = (options.description ?? `Custom ${id} skill`).trim();
+    const category = (options.category ?? "general");
+    if (!SKILL_CATEGORIES.includes(category)) {
+        console.error(chalk.red(`  Invalid category "${category}".\n  Allowed: ${SKILL_CATEGORIES.join(", ")}`));
+        process.exit(2);
+        return;
+    }
+    const harness = options.harness ?? "claude";
+    const baseDir = HARNESS_DIRS[harness];
+    if (!baseDir) {
+        console.error(chalk.red(`  Unknown harness "${harness}". Allowed: ${Object.keys(HARNESS_DIRS).join(", ")}`));
+        process.exit(2);
+        return;
+    }
+    const skillDir = path.join(cwd, baseDir, id);
+    const skillFile = path.join(skillDir, "SKILL.md");
+    if (fs.existsSync(skillFile) && !options.force) {
+        console.error(chalk.red(`  ${path.relative(cwd, skillFile)} already exists. Pass --force to overwrite.`));
+        process.exit(1);
+        return;
+    }
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(skillFile, renderSkillTemplate({ id, description, category }), "utf-8");
+    const rel = path.relative(cwd, skillFile);
+    console.log(chalk.green(`\n  Created ${rel}\n`));
+    console.log(chalk.dim("  Next steps:"));
+    console.log(chalk.dim(`    1. Open ${rel} and replace the placeholder sections.`));
+    console.log(chalk.dim(`    2. If your skill needs env vars, uncomment the 'config:' block in the frontmatter.`));
+    console.log(chalk.dim(`    3. If your skill executes tools via MCP, uncomment the 'mcp:' block.`));
+    console.log(chalk.dim(`    4. Reference the skill in a workflow node:  skills: [${id}]`));
+    console.log(chalk.dim(`    5. Run \`sweny skill list\` to confirm it discovers correctly.`));
+    console.log();
+}
+/**
+ * Action handler for `sweny skill list`. Exported for unit tests; production
+ * code goes through `registerSkillCommand`. `cwd` and `env` injection lets
+ * tests exercise the configured-badge logic without polluting global state.
+ */
+export function runSkillList(options, cwd = process.cwd(), env = process.env) {
+    // We want the FULL list (built-in + custom) even when env vars aren't set.
+    // configuredSkills filters by env, which hides authoring-time skills the
+    // user just scaffolded, so combine sources directly.
+    const { skills: customSkills, warnings: customWarnings } = discoverSkillsWithDiagnostics(cwd);
+    const customIds = new Set(customSkills.map((s) => s.id));
+    const builtinList = builtinSkills.filter((s) => !customIds.has(s.id));
+    // Configured map drives the "configured?" badge: required env vars present.
+    const configuredIds = new Set(configuredSkillsWithDiagnostics(env, cwd).skills.map((s) => s.id));
+    if (options.json) {
+        const data = [
+            ...builtinList.map((s) => ({
+                id: s.id,
+                kind: "builtin",
+                category: s.category,
+                description: s.description,
+                configured: configuredIds.has(s.id),
+            })),
+            ...customSkills.map((s) => ({
+                id: s.id,
+                kind: "custom",
+                category: s.category,
+                description: s.description,
+                configured: configuredIds.has(s.id),
+            })),
+        ];
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+        return;
+    }
+    const renderRow = (s, kind) => {
+        const tag = kind === "custom" ? chalk.magenta("custom") : chalk.dim("builtin");
+        const ok = configuredIds.has(s.id) ? chalk.green("✓") : chalk.yellow("·");
+        console.log(`  ${ok} ${chalk.cyan(s.id)} ${chalk.dim(`(${s.category})`)} ${tag}`);
+        console.log(chalk.dim(`      ${s.description}`));
+    };
+    console.log(chalk.bold("\nAvailable skills:\n"));
+    console.log(chalk.dim("  ✓ = configured (required env vars present)"));
+    console.log(chalk.dim("  · = present but not configured"));
+    console.log();
+    if (builtinList.length === 0 && customSkills.length === 0) {
+        console.log(chalk.dim("  (no skills found)\n"));
+    }
+    else {
+        for (const s of builtinList)
+            renderRow(s, "builtin");
+        for (const s of customSkills)
+            renderRow(s, "custom");
+    }
+    if (customWarnings.length > 0) {
+        console.log();
+        console.log(chalk.yellow(`  ${customWarnings.length} skill discovery warning(s):`));
+        for (const w of customWarnings) {
+            console.log(chalk.yellow(`    ${w.kind}: ${w.message}`));
+        }
+    }
+    console.log();
+    console.log(chalk.dim(`  Scaffold a new skill:  sweny skill new <id>`));
+    console.log();
+}
+/** Register the `sweny skill` subcommand group on the parent program. */
+export function registerSkillCommand(program) {
+    const skillCmd = program.command("skill").description("Author and inspect skills");
+    skillCmd
+        .command("new <id>")
+        .description("Scaffold a new SKILL.md in .claude/skills/<id>/")
+        .option("-d, --description <text>", "One-line description (required field in frontmatter)")
+        .option("-c, --category <category>", `Skill category (${SKILL_CATEGORIES.join("|")})`, "general")
+        .option("--harness <harness>", `Where to place the skill (${Object.keys(HARNESS_DIRS).join("|")})`, "claude")
+        .option("--force", "Overwrite an existing SKILL.md")
+        .action((id, options) => runSkillNew(id, options));
+    skillCmd
+        .command("list")
+        .description("List built-in and custom skills together with configuration status")
+        .option("--json", "Output as JSON array")
+        .action((options) => runSkillList(options));
+}

package/dist/schema.d.ts

@@ -241,7 +241,7 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     id: string;
     name: string;
     description: string;
-    category: "git" | "observability" | "tasks" | "notification" | "general";
+    category: "general" | "git" | "tasks" | "notification" | "observability";
     config: Record<string, {
         description: string;
         required?: boolean | undefined;
@@ -266,7 +266,7 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     id: string;
     name: string;
     description: string;
-    category: "git" | "observability" | "tasks" | "notification" | "general";
+    category: "general" | "git" | "tasks" | "notification" | "observability";
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;
@@ -291,7 +291,7 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     id: string;
     name: string;
     description: string;
-    category: "git" | "observability" | "tasks" | "notification" | "general";
+    category: "general" | "git" | "tasks" | "notification" | "observability";
     config: Record<string, {
         description: string;
         required?: boolean | undefined;
@@ -316,7 +316,7 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     id: string;
     name: string;
     description: string;
-    category: "git" | "observability" | "tasks" | "notification" | "general";
+    category: "general" | "git" | "tasks" | "notification" | "observability";
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;

package/dist/skills/custom-loader.js

@@ -11,6 +11,7 @@
 import { readdirSync, readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import YAML from "yaml";
+import { SKILL_CATEGORIES } from "../types.js";
 import { builtinSkills, isSkillConfigured } from "./index.js";
 /** Directories to scan, in ascending priority order. Last match wins. */
 const SKILL_DIRS = [".gemini/skills", ".agents/skills", ".claude/skills", ".sweny/skills"];
@@ -99,6 +100,9 @@ function parseSkillMd(content, path) {
     }
     // Narrow the loosely-typed YAML output into the fields we expect
     const fm = raw;
+    const category = typeof fm.category === "string" && SKILL_CATEGORIES.includes(fm.category)
+        ? fm.category
+        : "general";
     const id = String(fm.name);
     if (!VALID_SKILL_ID.test(id) || id.includes("--") || id.length > 64) {
         return {
@@ -145,7 +149,7 @@ function parseSkillMd(content, path) {
             id,
             name: id,
             description: typeof fm.description === "string" ? fm.description : `Custom skill: ${id}`,
-            category: "general",
+            category,
             config,
             tools: [],
             instruction: instruction || undefined,

package/dist/types.d.ts

@@ -22,8 +22,16 @@ export interface ConfigField {
     /** Default environment variable to read from */
     env?: string;
 }
-/** Skill categories — used for validation and grouping */
-export type SkillCategory = "git" | "observability" | "tasks" | "notification" | "general";
+/**
+ * Skill categories: used for per-node validation and grouping.
+ *
+ * Single source of truth for runtime + compile-time. The `as const` tuple
+ * lets the CLI iterate it for help text and the loader use it for runtime
+ * validation; `SkillCategory` is derived so adding a category requires
+ * only this line.
+ */
+export declare const SKILL_CATEGORIES: readonly ["general", "git", "tasks", "notification", "observability", "data"];
+export type SkillCategory = (typeof SKILL_CATEGORIES)[number];
 /** A skill groups related tools with shared config requirements */
 export interface Skill {
     id: string;

package/dist/types.js

@@ -1,3 +1,12 @@
+/**
+ * Skill categories: used for per-node validation and grouping.
+ *
+ * Single source of truth for runtime + compile-time. The `as const` tuple
+ * lets the CLI iterate it for help text and the loader use it for runtime
+ * validation; `SkillCategory` is derived so adding a category requires
+ * only this line.
+ */
+export const SKILL_CATEGORIES = ["general", "git", "tasks", "notification", "observability", "data"];
 export const consoleLogger = {
     info: (msg, data) => console.log(`[info] ${msg}`, data ?? ""),
     warn: (msg, data) => console.warn(`[warn] ${msg}`, data ?? ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"