talentos 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 A thin [stdio MCP](https://modelcontextprotocol.io) server that wraps the TalentOS
 external HTTP API (`/api/v0/*`). Point any MCP-capable agent (Claude Code, Claude
 Desktop, Cursor, etc.) at it and the agent can read your org's workflows and
-nodes, then create or replace workflow drafts through the same API key.
+nodes, then create or replace its own private Skills through the same API key.
 
 Published to npm as [`talentos`](https://www.npmjs.com/package/talentos) — run it
 with `npx -y talentos`, no checkout or build required.
@@ -20,14 +20,14 @@ It exposes six tools:
   agent-ready Markdown runbook, including its `**Version:**` stamp.
 - **`list_nodes`** (no arguments) — company-wide reusable nodes as name, id,
   step type, summary, and tools.
-- **`create_workflow`** (`{ title, steps, connections }`) — create a new draft
-  workflow from a full plan. Steps may include `outputs`, `successCriteria`, and
-  `runtime` contract fields. Writes always create drafts; a human publishes in
-  the app.
-- **`update_workflow`** (`{ workflowId, title, steps, connections }`) —
-  replace an existing draft workflow from a full plan. Steps may include
-  `outputs`, `successCriteria`, and `runtime`; published workflows return a
-  clear conflict instead of being edited.
+- **`create_skill`** (`{ name, summary, instructions, successCriteria?,
+  requestedTools? }`) — create a new Skill from plain-text instructions.
+  Returns the new `skillId` and its version. The Skill is private to the API
+  key's owner, who curates it in their TalentOS Skills library.
+- **`update_skill`** (`{ skillId, name, summary, instructions,
+  successCriteria?, requestedTools? }`) — replace one of the API key owner's
+  private Skills with a complete new body. Only that owner's private Skills are
+  writable; published and shared Skills stay human-owned.
 
 The server holds no state and stores nothing. Every call is a single
 authenticated request to the HTTP API; all authorization and visibility rules
@@ -56,7 +56,7 @@ npx -y talentos
 The `-y` skips the install prompt so noninteractive MCP clients don't hang. The
 first launch does a one-time network fetch to populate the npx cache (then exits
 asking for `TALENTOS_API_KEY`); run it once by hand — or pin a version like
-`talentos@0.2.0` — before wiring it into an offline or CI environment.
+`talentos@0.3.0` — before wiring it into an offline or CI environment.
 
 ## Add it to Claude Code
 
@@ -106,21 +106,20 @@ Add this to your MCP client config (`.mcp.json`, Claude Desktop config, etc.):
 3. **Add the server** to your MCP client using a snippet above, with your real
    key (the API URL defaults to production).
 
-4. **Ask the agent** to list your workflows, then create a draft:
+4. **Ask the agent** to list your workflows, then create a Skill:
 
    > List my TalentOS workflows, show me the first one as markdown, then create
-   > a new draft workflow for candidate outreach.
+   > a Skill for candidate outreach.
 
-   The agent calls `list_workflows`, `get_workflow`, and `create_workflow`. The
-   new workflow lands as a draft in TalentOS for a human to review and publish.
+   The agent calls `list_workflows`, `get_workflow`, and `create_skill`. The new
+   Skill lands as a private Skill in TalentOS for its owner to review.
 
 ## Errors you might see
 
 - **Unauthorized (401)** — `TALENTOS_API_KEY` is missing, wrong, or revoked.
-- **Workflow not found (404)** — the `id` doesn't exist or it is not visible to
-  this API key.
-- **Published workflow conflict (409)** — `update_workflow` only edits drafts;
-  published workflows must be duplicated or edited in TalentOS.
+- **Not found (404)** — the workflow or skill `id` doesn't exist, or it is not
+  visible to this API key. `update_skill` only reaches the key owner's own
+  private Skills.
 - **Rate limited (429)** — the key is over its requests-per-minute budget;
   wait a moment and retry.
 - **Could not reach the API** — `TALENTOS_API_URL` is wrong or unreachable;

package/dist/api.js

@@ -7,6 +7,7 @@
 const WORKFLOWS_PATH = "/api/v0/workflows";
 const NODES_PATH = "/api/v0/nodes";
 const CONTEXT_PATH = "/api/v0/context";
+const SKILLS_PATH = "/api/v0/skills";
 // A hung deployment (connection accepted, no response) would otherwise leave the
 // tool call pending forever with no error; abort so it surfaces as networkError.
 const REQUEST_TIMEOUT_MS = 15_000;
@@ -98,24 +99,24 @@ export async function getContext(config) {
     // formatting opinion belongs server-side, not in this wrapper.
     return textResult(JSON.stringify(result.body, null, 2));
 }
-export async function createWorkflow(config, plan) {
-    return await writeWorkflow(config, WORKFLOWS_PATH, plan, "Created");
+export async function createSkill(config, skill) {
+    return await writeSkill(config, SKILLS_PATH, skill, "Created");
 }
-export async function updateWorkflow(config, workflowId, plan) {
-    return await writeWorkflow(config, `${WORKFLOWS_PATH}/${encodeURIComponent(workflowId)}`, plan, "Updated", workflowId);
+export async function updateSkill(config, skillId, skill) {
+    return await writeSkill(config, `${SKILLS_PATH}/${encodeURIComponent(skillId)}`, skill, "Updated", skillId);
 }
 const URL_HINT = "The TALENTOS_API_URL may be wrong — it must point at the deployment's https://<name>.convex.site domain.";
-async function writeWorkflow(config, path, plan, action, workflowId) {
-    const result = await fetchJson(config, path, path === WORKFLOWS_PATH ? "POST" : "PUT", plan, workflowId);
+async function writeSkill(config, path, skill, action, skillId) {
+    const result = await fetchJson(config, path, path === SKILLS_PATH ? "POST" : "PUT", skill);
     if ("error" in result) {
         return result.error;
     }
-    const id = result.body.id ?? workflowId;
-    const status = result.body.status ?? "draft";
-    if (!id) {
-        return toolError(`The response was missing a workflow id. ${URL_HINT}`);
+    const id = result.body.skillId ?? skillId;
+    const version = result.body.version;
+    if (!id || version === undefined) {
+        return toolError(`The response was missing a skill id or version. ${URL_HINT}`);
     }
-    return textResult(`${action} workflow draft (id: ${id}) · status: ${status}\nA human must publish it in TalentOS.`);
+    return textResult(`${action} skill (id: ${id}) · version ${version}\nPrivate to this API key's owner; they curate it in their TalentOS Skills library.`);
 }
 function textResult(text) {
     return { content: [{ text, type: "text" }] };
@@ -136,7 +137,7 @@ async function httpError(response, workflowId) {
     }
     if (response.status === 409) {
         return toolError(message ??
-            "This workflow is published and can't be edited through the API.");
+            "This write conflicts with the current state. Reload and retry.");
     }
     if (response.status === 429) {
         return toolError("Rate limited (429). This API key is over its requests-per-minute budget — wait a moment and retry.");

package/dist/index.js

@@ -5,74 +5,27 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createWorkflow, getContext, getWorkflow, listNodes, listWorkflows, updateWorkflow, } from "./api.js";
+import { createSkill, getContext, getWorkflow, listNodes, listWorkflows, updateSkill, } from "./api.js";
 const TRAILING_SLASHES = /\/+$/;
 // The production TalentOS API origin. The server defaults to it so users only
 // need to supply TALENTOS_API_KEY; set TALENTOS_API_URL to override (e.g. a dev
 // deployment). Must be the .convex.site HTTP-action domain, not .convex.cloud.
 const DEFAULT_API_URL = "https://woozy-oyster-769.convex.site";
-const WORKFLOW_STEP_SCHEMA = z.object({
-    key: z.string().describe("Short kebab-case slug, unique per step."),
-    title: z.string().describe("Short imperative phrase, at most 8 words."),
-    stepType: z.enum(["human", "ai_assisted", "ai_agent", "automation"]),
-    description: z
+const SKILL_SCHEMA = {
+    instructions: z
         .string()
-        .optional()
-        .describe("Complete markdown instructions for the step."),
-    dataNeeded: z
-        .array(z.object({
-        label: z.string().describe("Short input name."),
-        detail: z
-            .string()
-            .optional()
-            .describe("Optional detail about the input."),
-    }))
-        .optional()
-        .describe("Inputs the step needs."),
-    outputs: z
-        .array(z.object({
-        label: z.string().describe("Artifact or deliverable name."),
-        detail: z
-            .string()
-            .optional()
-            .describe("Optional detail about the output."),
-        format: z
-            .string()
-            .optional()
-            .describe("Optional format hint, such as markdown, json, or url."),
-    }))
-        .optional()
-        .describe("Artifacts or deliverables the step produces."),
-    successCriteria: z
-        .string()
-        .optional()
-        .describe("How a reviewer or agent knows this step is done well."),
-    runtime: z
-        .object({
-        kind: z
-            .string()
-            .describe('Runtime the user named, such as "claude-code" or "api".'),
-        model: z.string().optional().describe("Optional model name."),
-        config: z
-            .record(z.string(), z.string())
-            .optional()
-            .describe("Optional string config for the runtime."),
-    })
-        .optional()
-        .describe("What executes this step, when the user names a runtime."),
-    toolNames: z
+        .describe("Complete plain-text instructions for the Skill."),
+    name: z.string().describe("Short title for the Skill."),
+    requestedTools: z
         .array(z.string())
         .optional()
         .describe("Tool names exactly as the user named them."),
-});
-const WORKFLOW_CONNECTION_SCHEMA = z.object({
-    fromKey: z.string().describe("The source step key."),
-    toKey: z.string().describe("The target step key."),
-    label: z
+    successCriteria: z
         .string()
         .optional()
-        .describe("Short branch label, only when the flow branches."),
-});
+        .describe("How a reviewer knows the Skill did its job well."),
+    summary: z.string().describe("One-sentence summary of what the Skill does."),
+};
 async function main() {
     const config = loadConfig();
     const server = new McpServer({
@@ -100,42 +53,30 @@ async function main() {
         title: "Get org context",
         description: "One compact summary of the org this API key belongs to: company profile basics plus the names of its published workflows and nodes. Call this first to prime yourself.",
     }, () => getContext(config));
-    server.registerTool("create_workflow", {
-        title: "Create workflow draft",
-        description: "Create a new TalentOS workflow draft from a full title/steps/connections plan. Steps may include agent contract fields: outputs, successCriteria, and runtime. Writes always create drafts that a human publishes in the app.",
-        inputSchema: {
-            title: z.string().describe("Short name for the whole workflow."),
-            steps: z
-                .array(WORKFLOW_STEP_SCHEMA)
-                .describe("The ordered workflow steps to materialize."),
-            connections: z
-                .array(WORKFLOW_CONNECTION_SCHEMA)
-                .optional()
-                .describe("Directed edges between the steps. Omit for no edges."),
-        },
-    }, ({ connections, steps, title }) => createWorkflow(config, {
-        connections: connections ?? [],
-        steps,
-        title,
+    server.registerTool("create_skill", {
+        title: "Create Skill",
+        description: "Create a new private TalentOS Skill from a name, summary, instructions, and success criteria. The Skill is private to the API key's owner, who curates it in TalentOS.",
+        inputSchema: SKILL_SCHEMA,
+    }, ({ instructions, name, requestedTools, successCriteria, summary }) => createSkill(config, {
+        instructions,
+        name,
+        ...(requestedTools === undefined ? {} : { requestedTools }),
+        ...(successCriteria === undefined ? {} : { successCriteria }),
+        summary,
     }));
-    server.registerTool("update_workflow", {
-        title: "Replace workflow draft",
-        description: "Replace an existing TalentOS workflow draft with a full title/steps/connections plan. Steps may include agent contract fields: outputs, successCriteria, and runtime. Drafts only: updating a published workflow returns a clear conflict message.",
+    server.registerTool("update_skill", {
+        title: "Replace Skill",
+        description: "Replace the API key owner's private TalentOS Skill with a complete name, summary, instructions, and success criteria.",
         inputSchema: {
-            workflowId: z.string().describe("The workflow id from list_workflows."),
-            title: z.string().describe("Short name for the whole workflow."),
-            steps: z
-                .array(WORKFLOW_STEP_SCHEMA)
-                .describe("The complete replacement step list."),
-            connections: z
-                .array(WORKFLOW_CONNECTION_SCHEMA)
-                .optional()
-                .describe("The complete replacement edge list. Omit for no edges."),
+            skillId: z.string().describe("The skill id from create_skill."),
+            ...SKILL_SCHEMA,
         },
-    }, ({ connections, steps, title, workflowId }) => updateWorkflow(config, workflowId, {
-        connections: connections ?? [],
-        steps,
-        title,
+    }, ({ instructions, name, requestedTools, skillId, successCriteria, summary, }) => updateSkill(config, skillId, {
+        instructions,
+        name,
+        ...(requestedTools === undefined ? {} : { requestedTools }),
+        ...(successCriteria === undefined ? {} : { successCriteria }),
+        summary,
     }));
     await server.connect(new StdioServerTransport());
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "talentos",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and draft writes.",
+  "description": "Stdio MCP server wrapping the TalentOS external HTTP API for workflow reads and private Skill writes.",
   "bin": {
     "talentos": "./dist/index.js"
   },
@@ -23,8 +23,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "tsx": "^4.22.5",
+    "@types/node": "^22",
+    "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   }
 }