@workplane/agent-skills 0.3.1

package/README.md

@@ -0,0 +1,52 @@
+# @workplane/agent-skills
+
+Pre-built agentic workplans and the `CanonicalSkillWorkflow` interface for building structured AI skills on top of `@workplane/workplans`.
+
+## Install
+
+```bash
+npm install @workplane/agent-skills @workplane/workplans
+```
+
+## Built-in skills
+
+### `code-review`
+
+Git diff → local summarize (ollama) → frontier critique (anthropic).
+
+```ts
+import { createDefaultRegistry, SequentialWorkplanRunner, LocalWorkplanContext } from "@workplane/agent-skills";
+import { SequentialWorkplanRunner } from "@workplane/workplans";
+
+const registry = createDefaultRegistry();
+const skill = registry.get("code-review");
+const plan = skill.buildPlan({ repo: "./my-repo", model: "claude-haiku-4-5-20251001" });
+await new SequentialWorkplanRunner().run(plan, new LocalWorkplanContext());
+```
+
+### `summarize-file`
+
+Read file → summarize with configurable provider (default: ollama).
+
+```ts
+const plan = registry.get("summarize-file").buildPlan({ file: "./README.md" });
+```
+
+## `CanonicalSkillWorkflow` interface
+
+For complex skills with structured input validation, context building, and persistent output:
+
+```ts
+import type { CanonicalSkillWorkflow } from "@workplane/agent-skills";
+import { CanonicalSkillRunner } from "@workplane/agent-skills";
+
+class MySkill implements CanonicalSkillWorkflow<MyInput, MyOutput> {
+  async resolveInputs(raw) { ... }
+  async buildContext(inputs) { ... }
+  async invokeAI(context) { ... }
+  async persistOutput(output) { ... }
+  async notify(ref) { ... }  // optional — failure never fails the run
+}
+
+const result = await new CanonicalSkillRunner().run(new MySkill(), input);
+```

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { WorkplanRunContext, Workplan } from '@workplane/workplans';
+
+interface ResolvedInputs<TInput> {
+    raw: TInput;
+}
+interface SkillContext {
+    inputs: Record<string, unknown>;
+    ctx: WorkplanRunContext;
+}
+interface AIOutput<TOutput> {
+    result: TOutput;
+    metadata?: Record<string, unknown>;
+}
+interface OutputRef {
+    type: string;
+    id: string;
+    [key: string]: unknown;
+}
+interface CanonicalSkillWorkflow<TInput = unknown, TOutput = unknown> {
+    resolveInputs(raw: TInput): Promise<ResolvedInputs<TInput>>;
+    buildContext(inputs: ResolvedInputs<TInput>): Promise<SkillContext>;
+    invokeAI(context: SkillContext): Promise<AIOutput<TOutput>>;
+    persistOutput(output: AIOutput<TOutput>): Promise<OutputRef>;
+    notify?(ref: OutputRef): Promise<void>;
+}
+interface SkillRunResult<TOutput> {
+    output: TOutput;
+    ref: OutputRef;
+    metadata?: Record<string, unknown>;
+}
+interface SkillEntry {
+    name: string;
+    description: string;
+    buildPlan(options: Record<string, unknown>): Workplan;
+}
+
+declare class CanonicalSkillRunner {
+    run<TInput, TOutput>(skill: CanonicalSkillWorkflow<TInput, TOutput>, input: TInput): Promise<SkillRunResult<TOutput>>;
+}
+
+declare class SkillRegistry {
+    private readonly skills;
+    register(entry: SkillEntry): void;
+    get(name: string): SkillEntry | undefined;
+    list(): SkillEntry[];
+}
+declare function createDefaultRegistry(): SkillRegistry;
+declare function listSkills(registry: SkillRegistry): void;
+
+interface CodeReviewOptions {
+    repoPath?: string;
+    model?: string;
+    branch?: string;
+}
+declare function codeReviewPlan(opts?: CodeReviewOptions): Workplan;
+
+interface SummarizeFileOptions {
+    filePath: string;
+    provider?: string;
+    model?: string;
+}
+declare function summarizeFilePlan(opts: SummarizeFileOptions): Workplan;
+
+export { type AIOutput, CanonicalSkillRunner, type CanonicalSkillWorkflow, type OutputRef, type ResolvedInputs, type SkillContext, type SkillEntry, SkillRegistry, type SkillRunResult, codeReviewPlan, createDefaultRegistry, listSkills, summarizeFilePlan };

package/dist/index.js

@@ -0,0 +1,135 @@
+// src/runner.ts
+var CanonicalSkillRunner = class {
+  async run(skill, input) {
+    const resolved = await skill.resolveInputs(input);
+    const context = await skill.buildContext(resolved);
+    const aiOutput = await skill.invokeAI(context);
+    const ref = await skill.persistOutput(aiOutput);
+    if (skill.notify) {
+      try {
+        await skill.notify(ref);
+      } catch {
+      }
+    }
+    return { output: aiOutput.result, ref, metadata: aiOutput.metadata };
+  }
+};
+
+// src/skills/code-review.ts
+function codeReviewPlan(opts = {}) {
+  const { repoPath = ".", model = "claude-haiku-4-5-20251001", branch } = opts;
+  const diffCmd = branch ? `git diff ${branch}..HEAD` : "git diff HEAD~1";
+  return {
+    id: "code-review",
+    name: "Code Review",
+    steps: [
+      {
+        id: "diff",
+        name: "Git Diff",
+        adapter: "shell",
+        provider: "shell",
+        payload: { command: diffCmd, cwd: repoPath },
+        output: { dest: "next" }
+      },
+      {
+        id: "summarize",
+        name: "Summarize",
+        adapter: "ollama",
+        provider: "ollama",
+        model: "llama3",
+        payload: { prompt: "Summarize these code changes concisely:\n{{prevOutput}}" },
+        output: { dest: "next" }
+      },
+      {
+        id: "critique",
+        name: "Critique",
+        adapter: "anthropic",
+        provider: "anthropic",
+        model,
+        payload: { prompt: "Review this summary for correctness, security issues, and code quality:\n{{prevOutput}}" }
+      }
+    ]
+  };
+}
+
+// src/skills/summarize-file.ts
+function summarizeFilePlan(opts) {
+  const { filePath, provider = "ollama", model = "llama3" } = opts;
+  return {
+    id: "summarize-file",
+    name: "Summarize File",
+    steps: [
+      {
+        id: "read",
+        name: "Read File",
+        adapter: "file",
+        provider: "file",
+        payload: { path: filePath },
+        output: { dest: "next" }
+      },
+      {
+        id: "summarize",
+        name: "Summarize",
+        adapter: provider,
+        provider,
+        model,
+        payload: { prompt: "Summarize the following file content concisely:\n{{prevOutput}}" }
+      }
+    ]
+  };
+}
+
+// src/skills/index.ts
+var SkillRegistry = class {
+  skills = /* @__PURE__ */ new Map();
+  register(entry) {
+    this.skills.set(entry.name, entry);
+  }
+  get(name) {
+    return this.skills.get(name);
+  }
+  list() {
+    return Array.from(this.skills.values());
+  }
+};
+function createDefaultRegistry() {
+  const registry = new SkillRegistry();
+  registry.register({
+    name: "code-review",
+    description: "Git diff \u2192 local summarize (ollama) \u2192 frontier critique (anthropic)",
+    buildPlan: (opts) => codeReviewPlan({
+      repoPath: typeof opts.repo === "string" ? opts.repo : void 0,
+      model: typeof opts.model === "string" ? opts.model : void 0,
+      branch: typeof opts.branch === "string" ? opts.branch : void 0
+    })
+  });
+  registry.register({
+    name: "summarize-file",
+    description: "Read file \u2192 summarize with configurable provider (default: ollama)",
+    buildPlan: (opts) => {
+      const filePath = typeof opts.file === "string" ? opts.file : "";
+      if (!filePath) throw new Error("--file is required for summarize-file");
+      return summarizeFilePlan({
+        filePath,
+        provider: typeof opts.provider === "string" ? opts.provider : void 0,
+        model: typeof opts.model === "string" ? opts.model : void 0
+      });
+    }
+  });
+  return registry;
+}
+function listSkills(registry) {
+  for (const skill of registry.list()) {
+    process.stdout.write(`  ${skill.name.padEnd(20)} ${skill.description}
+`);
+  }
+}
+export {
+  CanonicalSkillRunner,
+  SkillRegistry,
+  codeReviewPlan,
+  createDefaultRegistry,
+  listSkills,
+  summarizeFilePlan
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runner.ts","../src/skills/code-review.ts","../src/skills/summarize-file.ts","../src/skills/index.ts"],"sourcesContent":["import type { CanonicalSkillWorkflow, SkillRunResult } from \"./types.js\";\n\nexport class CanonicalSkillRunner {\n  async run<TInput, TOutput>(\n    skill: CanonicalSkillWorkflow<TInput, TOutput>,\n    input: TInput,\n  ): Promise<SkillRunResult<TOutput>> {\n    const resolved = await skill.resolveInputs(input);\n    const context = await skill.buildContext(resolved);\n    const aiOutput = await skill.invokeAI(context);\n    const ref = await skill.persistOutput(aiOutput);\n\n    if (skill.notify) {\n      try {\n        await skill.notify(ref);\n      } catch {\n        // notify failure never fails the run\n      }\n    }\n\n    return { output: aiOutput.result, ref, metadata: aiOutput.metadata };\n  }\n}\n","import type { Workplan } from \"@workplane/workplans\";\n\nexport interface CodeReviewOptions {\n  repoPath?: string;\n  model?: string;\n  branch?: string;\n}\n\nexport function codeReviewPlan(opts: CodeReviewOptions = {}): Workplan {\n  const { repoPath = \".\", model = \"claude-haiku-4-5-20251001\", branch } = opts;\n  const diffCmd = branch ? `git diff ${branch}..HEAD` : \"git diff HEAD~1\";\n\n  return {\n    id: \"code-review\",\n    name: \"Code Review\",\n    steps: [\n      {\n        id: \"diff\",\n        name: \"Git Diff\",\n        adapter: \"shell\",\n        provider: \"shell\",\n        payload: { command: diffCmd, cwd: repoPath },\n        output: { dest: \"next\" },\n      },\n      {\n        id: \"summarize\",\n        name: \"Summarize\",\n        adapter: \"ollama\",\n        provider: \"ollama\",\n        model: \"llama3\",\n        payload: { prompt: \"Summarize these code changes concisely:\\n{{prevOutput}}\" },\n        output: { dest: \"next\" },\n      },\n      {\n        id: \"critique\",\n        name: \"Critique\",\n        adapter: \"anthropic\",\n        provider: \"anthropic\",\n        model,\n        payload: { prompt: \"Review this summary for correctness, security issues, and code quality:\\n{{prevOutput}}\" },\n      },\n    ],\n  };\n}\n","import type { Workplan } from \"@workplane/workplans\";\n\nexport interface SummarizeFileOptions {\n  filePath: string;\n  provider?: string;\n  model?: string;\n}\n\nexport function summarizeFilePlan(opts: SummarizeFileOptions): Workplan {\n  const { filePath, provider = \"ollama\", model = \"llama3\" } = opts;\n\n  return {\n    id: \"summarize-file\",\n    name: \"Summarize File\",\n    steps: [\n      {\n        id: \"read\",\n        name: \"Read File\",\n        adapter: \"file\",\n        provider: \"file\",\n        payload: { path: filePath },\n        output: { dest: \"next\" },\n      },\n      {\n        id: \"summarize\",\n        name: \"Summarize\",\n        adapter: provider,\n        provider,\n        model,\n        payload: { prompt: \"Summarize the following file content concisely:\\n{{prevOutput}}\" },\n      },\n    ],\n  };\n}\n","import type { SkillEntry } from \"../types.js\";\nimport { codeReviewPlan } from \"./code-review.js\";\nimport { summarizeFilePlan } from \"./summarize-file.js\";\n\nexport class SkillRegistry {\n  private readonly skills = new Map<string, SkillEntry>();\n\n  register(entry: SkillEntry): void {\n    this.skills.set(entry.name, entry);\n  }\n\n  get(name: string): SkillEntry | undefined {\n    return this.skills.get(name);\n  }\n\n  list(): SkillEntry[] {\n    return Array.from(this.skills.values());\n  }\n}\n\nexport function createDefaultRegistry(): SkillRegistry {\n  const registry = new SkillRegistry();\n\n  registry.register({\n    name: \"code-review\",\n    description: \"Git diff → local summarize (ollama) → frontier critique (anthropic)\",\n    buildPlan: (opts) =>\n      codeReviewPlan({\n        repoPath: typeof opts.repo === \"string\" ? opts.repo : undefined,\n        model: typeof opts.model === \"string\" ? opts.model : undefined,\n        branch: typeof opts.branch === \"string\" ? opts.branch : undefined,\n      }),\n  });\n\n  registry.register({\n    name: \"summarize-file\",\n    description: \"Read file → summarize with configurable provider (default: ollama)\",\n    buildPlan: (opts) => {\n      const filePath = typeof opts.file === \"string\" ? opts.file : \"\";\n      if (!filePath) throw new Error(\"--file is required for summarize-file\");\n      return summarizeFilePlan({\n        filePath,\n        provider: typeof opts.provider === \"string\" ? opts.provider : undefined,\n        model: typeof opts.model === \"string\" ? opts.model : undefined,\n      });\n    },\n  });\n\n  return registry;\n}\n\nexport function listSkills(registry: SkillRegistry): void {\n  for (const skill of registry.list()) {\n    process.stdout.write(`  ${skill.name.padEnd(20)} ${skill.description}\\n`);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@workplane/agent-skills",
+  "version": "0.3.1",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MindStaq/workplane.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@workplane/workplans": "0.3.1"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}