Skill Authoring

Skill Authoring (Prismer)

You generate Prismer-standard skill drafts. You do NOT publish — that's a separate lifecycle step the user reviews via Studio Authoring (/evolution → Studio → Authoring).

Pipeline

1. Capture intent — clarify slug / name / trigger phrases / input-output / source kind. The four valid source kinds are:
   • inline-spec — extract from the active conversation context
   • doc-url — fetch markdown / OpenAPI / README from a URL
   • code-source — grep existing repo paths and bundle matched snippets
   • service-endpoint— probe an HTTP / MCP server's tool/endpoint catalog
2. Fetch sources — based on source kind:
   • inline-spec: extract directly from the chat history; do not call out
   • doc-url: cloud load <url> → returns compressed reference text (positional URL arg — there is NO --url flag)
   • code-source: cloud code grep <pattern> --repo <abs-path> → returns matched snippets to bundle as references/*
   • service-endpoint: cloud service introspect <url> → returns tool / endpoint list to translate into a SKILL.md workflow
3. Compose manifest v1 — write:
   • SKILL.md (frontmatter name/description/license/compatibility + a body that follows Anthropic skill-creator's progressive-disclosure pattern)
   • skill.json (structured SkillPackageSpec — see release201/07 §2.6)
   • Optional scripts/, references/, assets/
4. Submit draft — cloud skill draft create --slug <slug> --manifest <path> which calls POST /api/im/skills/draft. The cloud server runs the 7 validation gates and returns { id, slug, manifestRevision, reviewTaskId } on success.
5. Report draft id — surface the draft id back to the user; do NOT auto-publish.

Scenario 1 — API doc / URL → skill + callable script + auto tests

This is the canonical, quantifiable path (release201/24). When the user gives you an API document, an OpenAPI/Swagger spec, or a doc URL and asks to "make this a skill", produce a draft that can be VERIFIED by real dispatch — not just prose. Generate ALL of:

1. SKILL.md — workflow describing when/how to call the API, with the concrete endpoints, auth, and the script entrypoint.
2. scripts/call-api.* — a real, runnable script (Node .ts/.mjs, or .sh using curl) that performs the API call. Read inputs from argv / env; print the result to stdout. This is what the eval session actually exercises.
3. skill.json — the SkillPackageSpec with:
   • runtime.kind = 'inline-script' (or 'http-endpoint'), runtime.requires declaring bins/env the script needs (e.g. env: ["EXAMPLE_API_KEY"]).
   • inputs / outputs describing the call contract.
   • sampleTasks[] — at least 2 concrete tasks. EACH MUST have acceptanceCriteria[] written as substrings/regex that the dispatch OUTPUT must contain (e.g. "\"status\":\\s*200", "results"). These ARE the auto-generated mock tests — the daemon scorer matches them against the real dispatch output (release201/24 §2.1). A sampleTask with no acceptanceCriteria is scored inconclusive (NOT a pass), so always write them.
4. references/<api>.md — the compressed cloud load <url> / cloud service introspect <url> output, so the workflow is grounded.

Quantifiable acceptance: the skill is "good" when its eval run pass-rate (real dispatch of each sampleTask, scored against acceptanceCriteria) meets the lifecycle threshold. Write criteria that are tight enough to catch a broken call but not so tight they depend on volatile data.

Derive acceptanceCriteria from the spec: required response fields, status codes, schema keys. If the spec lacks examples, add a criterion asserting the script exits 0 and emits non-empty JSON, plus a field-presence check.

Boundaries

• DO NOT call POST /api/im/skills directly — it bypasses draft state
• DO NOT modify existing non-draft skills (use skill-creator reference if the user asks "edit existing skill")
• DO NOT trigger publish / share — the user reviews drafts in Studio Authoring
• Reference Anthropic skill-creator at /built-in-skills/skill-creator/SKILL.md for "how to write a good SKILL.md" patterns (progressive disclosure, allowed tool surface, etc.). Treat it as documentation, not as an executor.

Quality gates (self-check before submit)

The cloud server runs the 7 gates below at createDraft time and rejects with HTTP 400 on any blocking failure. Run the same checks locally before POSTing:

• name matches ^[a-z][a-z0-9-]*$
• description ≥ 50 chars, contains trigger context ("Use when...")
• SKILL.md body ≤ 500 lines (progressive disclosure)
• All scripts/refs/assets paths exist in manifest files[] array
• Merkle root computed correctly: sha256(join("\n", sorted(files, by=path).map(f => path + ":" + sha256)))

Output contract

After a successful submit, return to the user:

Copy code
Draft submitted.
  id:               <skill id>
  slug:             <slug>
  manifest revision <merkle>
  review task:      <task id>  (capability=skill-review, assignee=workspace owner)
  next step:        Open in Studio Authoring → review → promote to eval (release201/08)

Do NOT chain into install / publish; lifecycle is the workspace owner's call.