@sweny-ai/core 0.1.88 → 0.1.90

package/dist/cli/publish.js

@@ -15,9 +15,9 @@ import { parse as parseYaml } from "yaml";
 import { parseWorkflow, validateWorkflow } from "../schema.js";
 import { builtinSkills } from "../skills/index.js";
 import { discoverSkillsWithDiagnostics } from "../skills/custom-loader.js";
+import { isValidSkillId } from "../types.js";
 // ── Types ──────────────────────────────────────────────────────────────
 const VALID_CATEGORIES = ["triage", "security", "devops", "code-review", "testing", "content", "ops"];
-const VALID_SKILL_ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 // ── Validation helpers ─────────────────────────────────────────────────
 export function validateWorkflowFile(filePath) {
     const errors = [];
@@ -119,8 +119,8 @@ export function validateSkillDir(dirPath) {
     if (!id) {
         errors.push("Missing 'name' field in frontmatter");
     }
-    else if (!VALID_SKILL_ID.test(id) || id.includes("--") || id.length > 64) {
-        errors.push(`Invalid skill ID: "${id}" — must be lowercase, hyphens, no consecutive hyphens, max 64 chars`);
+    else if (!isValidSkillId(id)) {
+        errors.push(`Invalid skill ID: "${id}" (must be lowercase alphanumeric + hyphens, no consecutive hyphens, max 64 chars)`);
     }
     // Check directory name matches skill name
     const dirName = path.basename(dirPath);

package/dist/cli/skill.d.ts

@@ -14,14 +14,34 @@
  * and `../skills/index.js`; this CLI is a thin authoring shell over them.
  */
 import { Command } from "commander";
-declare const VALID_CATEGORIES: readonly ["general", "git", "tasks", "notification", "observability", "data"];
-type SkillCategory = (typeof VALID_CATEGORIES)[number];
+import { type SkillCategory, type SkillHarnessKey } from "../types.js";
 /** 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?: SkillHarnessKey;
+    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

@@ -18,15 +18,11 @@ import * as path from "node:path";
 import chalk from "chalk";
 import { builtinSkills } from "../skills/index.js";
 import { configuredSkillsWithDiagnostics, discoverSkillsWithDiagnostics } from "../skills/custom-loader.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 VALID_CATEGORIES = ["general", "git", "tasks", "notification", "observability", "data"];
-const HARNESS_DIRS = {
-    claude: ".claude/skills",
-    sweny: ".sweny/skills",
-    agents: ".agents/skills",
-    gemini: ".gemini/skills",
-};
+import { SKILL_CATEGORIES, SKILL_HARNESSES, isValidSkillId, } from "../types.js";
+// Lookup table: harness key -> directory. Built once from SKILL_HARNESSES so
+// the CLI cannot drift from the loader's scan list.
+const HARNESS_DIRS = Object.fromEntries(SKILL_HARNESSES.map((h) => [h.key, h.path]));
+const HARNESS_KEYS = SKILL_HARNESSES.map((h) => h.key);
 /** Build the SKILL.md body for a fresh scaffold. Exported for tests. */
 export function renderSkillTemplate(opts) {
     const { id, description, category } = opts;
@@ -80,28 +76,32 @@ export function renderSkillTemplate(opts) {
     lines.push("");
     return lines.join("\n");
 }
-function runSkillNew(idArg, options) {
+/**
+ * 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) {
+    if (!isValidSkillId(id)) {
         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 (!VALID_CATEGORIES.includes(category)) {
-        console.error(chalk.red(`  Invalid category "${category}".\n  Allowed: ${VALID_CATEGORIES.join(", ")}`));
+    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(", ")}`));
+        console.error(chalk.red(`  Unknown harness "${harness}". Allowed: ${HARNESS_KEYS.join(", ")}`));
         process.exit(2);
         return;
     }
-    const cwd = process.cwd();
     const skillDir = path.join(cwd, baseDir, id);
     const skillFile = path.join(skillDir, "SKILL.md");
     if (fs.existsSync(skillFile) && !options.force) {
@@ -121,16 +121,20 @@ function runSkillNew(idArg, options) {
     console.log(chalk.dim(`    5. Run \`sweny skill list\` to confirm it discovers correctly.`));
     console.log();
 }
-function runSkillList(options) {
-    const cwd = process.cwd();
-    // 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.
+/**
+ * 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(process.env, cwd).skills.map((s) => 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) => ({
@@ -188,8 +192,8 @@ export function registerSkillCommand(program) {
         .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 (${VALID_CATEGORIES.join("|")})`, "general")
-        .option("--harness <harness>", `Where to place the skill (${Object.keys(HARNESS_DIRS).join("|")})`, "claude")
+        .option("-c, --category <category>", `Skill category (${SKILL_CATEGORIES.join("|")})`, "general")
+        .option("--harness <harness>", `Where to place the skill (${HARNESS_KEYS.join("|")})`, "claude")
         .option("--force", "Overwrite an existing SKILL.md")
         .action((id, options) => runSkillNew(id, options));
     skillCmd

package/dist/schema.d.ts

@@ -42,7 +42,7 @@ export declare const toolZ: z.ZodObject<{
     description: string;
     input_schema: Record<string, unknown>;
 }>;
-export declare const skillCategoryZ: z.ZodEnum<["git", "observability", "tasks", "notification", "general"]>;
+export declare const skillCategoryZ: z.ZodEnum<["general", "git", "tasks", "notification", "observability", "data"]>;
 export declare const mcpServerConfigZ: z.ZodEffects<z.ZodObject<{
     type: z.ZodOptional<z.ZodEnum<["stdio", "http"]>>;
     command: z.ZodOptional<z.ZodString>;
@@ -172,7 +172,7 @@ export declare const skillZ: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     description: z.ZodString;
-    category: z.ZodEnum<["git", "observability", "tasks", "notification", "general"]>;
+    category: z.ZodEnum<["general", "git", "tasks", "notification", "observability", "data"]>;
     config: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         description: z.ZodString;
         required: z.ZodOptional<z.ZodBoolean>;
@@ -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" | "data";
     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" | "data";
     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" | "data";
     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" | "data";
     instruction?: string | undefined;
     mcp?: {
         url?: string | undefined;
@@ -3002,3 +3002,160 @@ export declare const workflowJsonSchema: {
         };
     };
 };
+/**
+ * Skill JSON Schema, generated from runtime constants.
+ *
+ * Companion to {@link workflowJsonSchema}: published at
+ * https://spec.sweny.ai/schemas/skill.json by the
+ * `write-public-schema.mjs` build step. Validates the structural shape
+ * of a Skill (id, name, description, category, config, plus optional
+ * tools/instruction/mcp).
+ *
+ * Every enum and the `id` pattern + maxLength are imported from
+ * `types.ts` so adding a category, harness, transport, or changing the
+ * id rule updates the published schema with no manual sync.
+ */
+export declare const skillJsonSchema: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://spec.sweny.ai/schemas/skill.json";
+    readonly title: "SWEny Skill";
+    readonly description: "A composable tool bundle that provides capabilities to workflow nodes.";
+    readonly type: "object";
+    readonly required: readonly ["id", "name", "description", "category", "config"];
+    readonly anyOf: readonly [{
+        readonly required: readonly ["tools"];
+    }, {
+        readonly required: readonly ["instruction"];
+    }, {
+        readonly required: readonly ["mcp"];
+    }];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 64;
+            readonly pattern: string;
+            readonly description: "Unique skill identifier. Referenced by nodes' skills arrays. Lowercase kebab-case recommended.";
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Human-readable skill name.";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "What this skill provides.";
+        };
+        readonly category: {
+            readonly type: "string";
+            readonly enum: readonly ["general", "git", "tasks", "notification", "observability", "data"];
+            readonly description: "Functional category.";
+        };
+        readonly config: {
+            readonly type: "object";
+            readonly description: "Configuration fields required by this skill.";
+            readonly additionalProperties: {
+                readonly $ref: "#/$defs/ConfigField";
+            };
+        };
+        readonly tools: {
+            readonly type: "array";
+            readonly description: "Tools this skill provides to nodes.";
+            readonly items: {
+                readonly $ref: "#/$defs/Tool";
+            };
+        };
+        readonly instruction: {
+            readonly type: "string";
+            readonly description: "Natural language expertise injected into the node prompt when this skill is referenced.";
+        };
+        readonly mcp: {
+            readonly $ref: "#/$defs/McpServerConfig";
+            readonly description: "External MCP server definition wired for nodes referencing this skill.";
+        };
+    };
+    readonly $defs: {
+        readonly ConfigField: {
+            readonly type: "object";
+            readonly required: readonly ["description"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly description: {
+                    readonly type: "string";
+                    readonly description: "Human-readable description of this config field.";
+                };
+                readonly required: {
+                    readonly type: "boolean";
+                    readonly default: false;
+                    readonly description: "Whether this field must be provided for the skill to function.";
+                };
+                readonly env: {
+                    readonly type: "string";
+                    readonly description: "Default environment variable to read this value from.";
+                };
+            };
+        };
+        readonly Tool: {
+            readonly type: "object";
+            readonly required: readonly ["name", "description", "input_schema"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Tool name. Must be unique within the skill.";
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly description: "What this tool does. Provided to the AI model for tool selection.";
+                };
+                readonly input_schema: {
+                    readonly type: "object";
+                    readonly description: "JSON Schema defining the tool's input parameters.";
+                };
+            };
+        };
+        readonly McpServerConfig: {
+            readonly type: "object";
+            readonly description: "External MCP server definition.";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly type: "string";
+                    readonly enum: readonly ["stdio", "http"];
+                    readonly description: "Transport type. Inferred from presence of command (stdio) or url (http) when omitted.";
+                };
+                readonly command: {
+                    readonly type: "string";
+                    readonly description: "Spawn command (stdio transport).";
+                };
+                readonly args: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Arguments for the command.";
+                };
+                readonly url: {
+                    readonly type: "string";
+                    readonly format: "uri";
+                    readonly description: "HTTP endpoint (HTTP transport).";
+                };
+                readonly headers: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                    };
+                    readonly description: "HTTP headers (HTTP transport only).";
+                };
+                readonly env: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Environment variable names the server needs. Values are descriptions, not secrets.";
+                };
+            };
+        };
+    };
+};

package/dist/schema.js

@@ -7,6 +7,7 @@
  * parsing untrusted input (JSON/YAML import, Studio editor).
  */
 import { z } from "zod";
+import { EVALUATOR_KINDS, EVAL_POLICIES, MCP_TRANSPORTS, REQUIRES_ON_FAIL, SKILL_CATEGORIES, SKILL_ID_MAX_LENGTH, SKILL_ID_PATTERN, } from "./types.js";
 import { sourceZ } from "./sources.js";
 export { sourceZ };
 // ─── Zod Schemas ─────────────────────────────────────────────────
@@ -26,10 +27,10 @@ export const toolZ = z.object({
     description: z.string(),
     input_schema: jsonSchemaZ,
 });
-export const skillCategoryZ = z.enum(["git", "observability", "tasks", "notification", "general"]);
+export const skillCategoryZ = z.enum(SKILL_CATEGORIES);
 export const mcpServerConfigZ = z
     .object({
-    type: z.enum(["stdio", "http"]).optional(),
+    type: z.enum(MCP_TRANSPORTS).optional(),
     command: z.string().optional(),
     args: z.array(z.string()).optional(),
     url: z.string().optional(),
@@ -90,8 +91,8 @@ export const outputMatchZ = z
     const operators = [m.equals !== undefined, m.in !== undefined, m.matches !== undefined];
     return operators.filter(Boolean).length === 1;
 }, { message: "output_matches entry must declare exactly one of: equals, in, matches" });
-export const evaluatorKindZ = z.enum(["value", "function", "judge"]);
-export const evalPolicyZ = z.enum(["all_pass", "any_pass", "weighted"]);
+export const evaluatorKindZ = z.enum(EVALUATOR_KINDS);
+export const evalPolicyZ = z.enum(EVAL_POLICIES);
 export const evaluatorRuleZ = z
     .object({
     any_tool_called: z.array(z.string().min(1)).min(1).optional(),
@@ -170,7 +171,7 @@ export const nodeRequiresZ = z
     .object({
     output_required: z.array(z.string().min(1)).min(1).optional(),
     output_matches: z.array(outputMatchZ).min(1).optional(),
-    on_fail: z.enum(["fail", "skip"]).optional(),
+    on_fail: z.enum(REQUIRES_ON_FAIL).optional(),
 })
     .strict()
     .refine((r) => r.output_required !== undefined || r.output_matches !== undefined, {
@@ -482,7 +483,7 @@ export const workflowJsonSchema = {
                     minLength: 1,
                     description: "Stable identifier for this evaluator. Used in EvalResult and retry preambles.",
                 },
-                kind: { type: "string", enum: ["value", "function", "judge"] },
+                kind: { type: "string", enum: [...EVALUATOR_KINDS] },
                 rule: {
                     type: "object",
                     description: "Required for value and function kinds. Shape depends on kind.",
@@ -591,7 +592,7 @@ export const workflowJsonSchema = {
                     },
                     eval_policy: {
                         type: "string",
-                        enum: ["all_pass", "any_pass", "weighted"],
+                        enum: [...EVAL_POLICIES],
                         default: "all_pass",
                         description: "How evaluator results aggregate. v1 implements all_pass; the others are reserved.",
                     },
@@ -618,7 +619,7 @@ export const workflowJsonSchema = {
                                 items: { $ref: "#/$defs/OutputMatch" },
                                 minItems: 1,
                             },
-                            on_fail: { type: "string", enum: ["fail", "skip"] },
+                            on_fail: { type: "string", enum: [...REQUIRES_ON_FAIL] },
                         },
                     },
                     retry: {
@@ -689,7 +690,7 @@ export const workflowJsonSchema = {
                         // Round 2: reject unknown keys to match Zod mcpServerConfigZ.strict().
                         additionalProperties: false,
                         properties: {
-                            type: { type: "string", enum: ["stdio", "http"] },
+                            type: { type: "string", enum: [...MCP_TRANSPORTS] },
                             command: { type: "string" },
                             args: { type: "array", items: { type: "string" } },
                             url: { type: "string" },
@@ -702,3 +703,144 @@ export const workflowJsonSchema = {
         },
     },
 };
+/**
+ * Skill JSON Schema, generated from runtime constants.
+ *
+ * Companion to {@link workflowJsonSchema}: published at
+ * https://spec.sweny.ai/schemas/skill.json by the
+ * `write-public-schema.mjs` build step. Validates the structural shape
+ * of a Skill (id, name, description, category, config, plus optional
+ * tools/instruction/mcp).
+ *
+ * Every enum and the `id` pattern + maxLength are imported from
+ * `types.ts` so adding a category, harness, transport, or changing the
+ * id rule updates the published schema with no manual sync.
+ */
+export const skillJsonSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://spec.sweny.ai/schemas/skill.json",
+    title: "SWEny Skill",
+    description: "A composable tool bundle that provides capabilities to workflow nodes.",
+    type: "object",
+    required: ["id", "name", "description", "category", "config"],
+    anyOf: [{ required: ["tools"] }, { required: ["instruction"] }, { required: ["mcp"] }],
+    additionalProperties: false,
+    properties: {
+        id: {
+            type: "string",
+            minLength: 1,
+            maxLength: SKILL_ID_MAX_LENGTH,
+            pattern: SKILL_ID_PATTERN.source,
+            description: "Unique skill identifier. Referenced by nodes' skills arrays. Lowercase kebab-case recommended.",
+        },
+        name: {
+            type: "string",
+            minLength: 1,
+            description: "Human-readable skill name.",
+        },
+        description: {
+            type: "string",
+            description: "What this skill provides.",
+        },
+        category: {
+            type: "string",
+            enum: [...SKILL_CATEGORIES],
+            description: "Functional category.",
+        },
+        config: {
+            type: "object",
+            description: "Configuration fields required by this skill.",
+            additionalProperties: { $ref: "#/$defs/ConfigField" },
+        },
+        tools: {
+            type: "array",
+            description: "Tools this skill provides to nodes.",
+            items: { $ref: "#/$defs/Tool" },
+        },
+        instruction: {
+            type: "string",
+            description: "Natural language expertise injected into the node prompt when this skill is referenced.",
+        },
+        mcp: {
+            $ref: "#/$defs/McpServerConfig",
+            description: "External MCP server definition wired for nodes referencing this skill.",
+        },
+    },
+    $defs: {
+        ConfigField: {
+            type: "object",
+            required: ["description"],
+            additionalProperties: false,
+            properties: {
+                description: {
+                    type: "string",
+                    description: "Human-readable description of this config field.",
+                },
+                required: {
+                    type: "boolean",
+                    default: false,
+                    description: "Whether this field must be provided for the skill to function.",
+                },
+                env: {
+                    type: "string",
+                    description: "Default environment variable to read this value from.",
+                },
+            },
+        },
+        Tool: {
+            type: "object",
+            required: ["name", "description", "input_schema"],
+            additionalProperties: false,
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Tool name. Must be unique within the skill.",
+                },
+                description: {
+                    type: "string",
+                    description: "What this tool does. Provided to the AI model for tool selection.",
+                },
+                input_schema: {
+                    type: "object",
+                    description: "JSON Schema defining the tool's input parameters.",
+                },
+            },
+        },
+        McpServerConfig: {
+            type: "object",
+            description: "External MCP server definition.",
+            additionalProperties: false,
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [...MCP_TRANSPORTS],
+                    description: "Transport type. Inferred from presence of command (stdio) or url (http) when omitted.",
+                },
+                command: {
+                    type: "string",
+                    description: "Spawn command (stdio transport).",
+                },
+                args: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Arguments for the command.",
+                },
+                url: {
+                    type: "string",
+                    format: "uri",
+                    description: "HTTP endpoint (HTTP transport).",
+                },
+                headers: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "HTTP headers (HTTP transport only).",
+                },
+                env: {
+                    type: "object",
+                    additionalProperties: { type: "string" },
+                    description: "Environment variable names the server needs. Values are descriptions, not secrets.",
+                },
+            },
+        },
+    },
+};

package/dist/skills/custom-loader.js

@@ -11,11 +11,15 @@
 import { readdirSync, readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import YAML from "yaml";
+import { SKILL_CATEGORIES, SKILL_HARNESSES, isValidSkillId } 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"];
-/** Valid skill ID: lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, max 64 chars. */
-const VALID_SKILL_ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Directories to scan, in ascending priority order. Last match wins.
+ *
+ * Derived from {@link SKILL_HARNESSES} so the loader and the CLI authoring
+ * side cannot disagree on what counts as a skill harness directory.
+ */
+const SKILL_DIRS = SKILL_HARNESSES.map((h) => h.path);
 /**
  * Discover custom skills and surface diagnostics for broken ones.
  *
@@ -99,12 +103,11 @@ function parseSkillMd(content, path) {
     }
     // Narrow the loosely-typed YAML output into the fields we expect
     const fm = raw;
-    const VALID_CATEGORIES = ["general", "git", "tasks", "notification", "observability", "data"];
-    const category = typeof fm.category === "string" && VALID_CATEGORIES.includes(fm.category)
+    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) {
+    if (!isValidSkillId(id)) {
         return {
             kind: "err",
             diagnostic: {

package/dist/types.d.ts

@@ -22,8 +22,56 @@ 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" | "data" | "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];
+/**
+ * Skill harness directories, listed in ascending priority order.
+ *
+ * Both the loader (which scans these directories last-wins for ID
+ * collisions) and the CLI (which writes scaffolds into one of them)
+ * must agree on this list. A divergence means scaffolded skills land
+ * somewhere the loader doesn't read, or the loader reads from a
+ * directory the CLI can't target.
+ *
+ * Order matters: the loader treats later entries as higher priority,
+ * so `.sweny/skills/` overrides `.claude/skills/` on a name collision.
+ */
+export declare const SKILL_HARNESSES: readonly [{
+    readonly key: "gemini";
+    readonly path: ".gemini/skills";
+}, {
+    readonly key: "agents";
+    readonly path: ".agents/skills";
+}, {
+    readonly key: "claude";
+    readonly path: ".claude/skills";
+}, {
+    readonly key: "sweny";
+    readonly path: ".sweny/skills";
+}];
+export type SkillHarnessKey = (typeof SKILL_HARNESSES)[number]["key"];
+/**
+ * Skill ID validation rules, declared once for runtime + spec.
+ *
+ * The pattern excludes consecutive hyphens via a negative lookahead so a
+ * single regex is the whole rule. JSON Schema regex follows ECMA 262, which
+ * supports lookaheads, so the spec can embed this string directly.
+ *
+ * Length cap is enforced separately because JSON Schema's `maxLength` is
+ * the canonical place to express it (vs. cramming `{1,64}` into the regex).
+ */
+export declare const SKILL_ID_PATTERN: RegExp;
+export declare const SKILL_ID_MAX_LENGTH = 64;
+/** True when `id` is a structurally valid skill ID under the rules above. */
+export declare function isValidSkillId(id: string): boolean;
 /** A skill groups related tools with shared config requirements */
 export interface Skill {
     id: string;
@@ -69,9 +117,17 @@ export type NodeSources = _Source[] | {
     sources: _Source[];
 };
 /** Kind of evaluator. See {@link Evaluator}. */
-export type EvaluatorKind = "value" | "function" | "judge";
+export declare const EVALUATOR_KINDS: readonly ["value", "function", "judge"];
+export type EvaluatorKind = (typeof EVALUATOR_KINDS)[number];
 /** Aggregation policy for a node's evaluator results. v1 implements `all_pass`. */
-export type EvalPolicy = "all_pass" | "any_pass" | "weighted";
+export declare const EVAL_POLICIES: readonly ["all_pass", "any_pass", "weighted"];
+export type EvalPolicy = (typeof EVAL_POLICIES)[number];
+/** Action when a `requires` precondition fails. */
+export declare const REQUIRES_ON_FAIL: readonly ["fail", "skip"];
+export type RequiresOnFail = (typeof REQUIRES_ON_FAIL)[number];
+/** MCP server transport type. Inferred from command/url when omitted. */
+export declare const MCP_TRANSPORTS: readonly ["stdio", "http"];
+export type McpTransport = (typeof MCP_TRANSPORTS)[number];
 /**
  * The deterministic rule body for a `value` or `function` evaluator.
  *

package/dist/types.js

@@ -1,3 +1,54 @@
+/**
+ * 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"];
+/**
+ * Skill harness directories, listed in ascending priority order.
+ *
+ * Both the loader (which scans these directories last-wins for ID
+ * collisions) and the CLI (which writes scaffolds into one of them)
+ * must agree on this list. A divergence means scaffolded skills land
+ * somewhere the loader doesn't read, or the loader reads from a
+ * directory the CLI can't target.
+ *
+ * Order matters: the loader treats later entries as higher priority,
+ * so `.sweny/skills/` overrides `.claude/skills/` on a name collision.
+ */
+export const SKILL_HARNESSES = [
+    { key: "gemini", path: ".gemini/skills" },
+    { key: "agents", path: ".agents/skills" },
+    { key: "claude", path: ".claude/skills" },
+    { key: "sweny", path: ".sweny/skills" },
+];
+/**
+ * Skill ID validation rules, declared once for runtime + spec.
+ *
+ * The pattern excludes consecutive hyphens via a negative lookahead so a
+ * single regex is the whole rule. JSON Schema regex follows ECMA 262, which
+ * supports lookaheads, so the spec can embed this string directly.
+ *
+ * Length cap is enforced separately because JSON Schema's `maxLength` is
+ * the canonical place to express it (vs. cramming `{1,64}` into the regex).
+ */
+export const SKILL_ID_PATTERN = /^(?!.*--)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+export const SKILL_ID_MAX_LENGTH = 64;
+/** True when `id` is a structurally valid skill ID under the rules above. */
+export function isValidSkillId(id) {
+    return typeof id === "string" && id.length > 0 && id.length <= SKILL_ID_MAX_LENGTH && SKILL_ID_PATTERN.test(id);
+}
+/** Kind of evaluator. See {@link Evaluator}. */
+export const EVALUATOR_KINDS = ["value", "function", "judge"];
+/** Aggregation policy for a node's evaluator results. v1 implements `all_pass`. */
+export const EVAL_POLICIES = ["all_pass", "any_pass", "weighted"];
+/** Action when a `requires` precondition fails. */
+export const REQUIRES_ON_FAIL = ["fail", "skip"];
+/** MCP server transport type. Inferred from command/url when omitted. */
+export const MCP_TRANSPORTS = ["stdio", "http"];
 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.88",
+  "version": "0.1.90",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"
@@ -50,7 +50,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --exclude 'src/__tests__/integration/**' --exclude 'dist/**'",
     "test:integration": "vitest run --config vitest.integration.config.ts",
-    "check:schema-drift": "node scripts/write-public-schema.mjs && git diff --exit-code -- ../../spec/public/schemas/workflow.json"
+    "check:schema-drift": "node scripts/write-public-schema.mjs && git diff --exit-code -- ../../spec/public/schemas/workflow.json ../../spec/public/schemas/skill.json"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.114",