Prompt And Skill Quickstart

This quickstart creates a reusable prompt, attaches it to a draft skill version, previews the composed prompt, runs the skill, and inspects the resulting run.

Use this path when you want the shortest supported loop for editing a skill and its prompts together. Prompts hold reusable authored content. Skills hold executable configuration, tools, contracts, and versions.

Before you start

Create a PromptOrchestraClient with a credential that can use public beta authoring routes.

import { PromptOrchestraClient } from "@prompt-mv/orchestration";

const organizationId = process.env.PROMPT_ORCHESTRA_ORGANIZATION_ID!;

const client = new PromptOrchestraClient({
  baseUrl: process.env.PROMPT_ORCHESTRA_BASE_URL!,
  apiKey: process.env.PROMPT_ORCHESTRA_AUTHORING_API_KEY!,
});

1. Create a prompt

const prompt = await client.prompts.create({
  organizationId,
  promptKey: "support-answer-policy",
  name: "Support Answer Policy",
  defaultSection: "task_instructions",
});

2. Create and publish prompt content

const promptVersion = await client.prompts.createVersion(prompt.id, {
  organizationId,
  content:
    "Answer with one direct recommendation, cite the relevant constraint, and ask for missing information only when needed.",
});

await client.prompts.publish(prompt.id, {
  organizationId,
  versionId: promptVersion.id,
});

3. Create a skill and draft version

const skill = await client.skills.create({
  organizationId,
  skillKey: "support-answer",
  name: "Support Answer",
  description: "Answers support questions using the approved prompt policy.",
});

const skillVersion = await client.skills.createVersion(skill.id, {
  organizationId,
});

4. Attach the prompt to the skill version

await client.skills.replacePrompts(skillVersion.id, {
  organizationId,
  prompts: [
    {
      promptId: prompt.id,
      attachmentMode: "floating_latest_published",
      positionIndex: 0,
    },
  ],
});

replacePrompts is the canonical authored write path for skill prompt composition. The order of the prompts array is the skill version's prompt composition order.

5. Preview before running

const preview = await client.skills.preview(skill.id, {
  organizationId,
  skillVersionId: skillVersion.id,
  variables: {
    customerQuestion: "Can I use an authoring key for runtime calls?",
  },
});

console.log(preview.renderedPrompt);
console.log(preview.compositionTrace);

Preview renders composition without executing the skill.

6. Run and inspect

const run = await client.skills.run(skill.id, {
  organizationId,
  skillVersionId: skillVersion.id,
  variables: {
    customerQuestion: "Can I use an authoring key for runtime calls?",
  },
});

const detail = await client.runs.getSkillRun(run.runId, {
  organizationId,
});

console.log(detail.promptComposition);
console.log(detail.renderedPrompt);
console.log(detail.validation);

Run detail is the inspection surface. Use it to confirm which prompt composition ran, which version context was used, and whether validation or runtime diagnostics changed the outcome.

CLI equivalent

For CLI-managed authoring, declare reusable prompts at top level and reference them from skills[].promptComposition.

{
  "schemaVersion": "builder.desired-state.v1",
  "publishIntent": { "mode": "draft_only", "targetEnvironment": "dev" },
  "prompts": [
    {
      "promptKey": "support-answer-policy",
      "name": "Support Answer Policy",
      "defaultSection": "task_instructions",
      "content": "Answer with one direct recommendation.",
      "publish": true
    }
  ],
  "skills": [
    {
      "skillKey": "support-answer",
      "name": "Support Answer",
      "modelSelection": { "by": "modelKey", "modelKey": "gpt-4.1-mini" },
      "promptComposition": [
        {
          "promptKey": "support-answer-policy",
          "attachmentMode": "floating_latest_published",
          "positionIndex": 0
        }
      ],
      "toolBindings": []
    }
  ],
  "tools": [],
  "agents": [],
  "evaluations": [],
  "endpoints": []
}

Then run:

prompt-mv plan --spec ./desired-state.json
prompt-mv diff --spec ./desired-state.json
prompt-mv apply --spec ./desired-state.json
prompt-mv inspect --spec ./desired-state.json --mode both

The CLI rejects legacy layer-shaped skill specs instead of translating them silently.

Not covered here

This quickstart covers the supported standard prompt/skill path. It does not cover realtime execution, generated image output, prompt-stack compatibility routes, or reference-image workflows.