Skill

The Skill primitive defines a composed workflow — a higher-order capability built from multiple tools, with natural-language instructions for the LLM to follow. Skills are the CKP mechanism for portable, reusable multi-step workflows.

URI pattern: claw://local/skill/{name}

---

Schema

claw: "0.3.0"
kind: Skill
metadata:
  name: "deep-research"
  version: "2.0.0"
  labels:
    domain: "research"
spec:
  description: |
    Conduct deep research on a given topic by searching multiple sources,
    cross-referencing findings, and producing a structured report with
    citations and confidence assessments.

  tools_required:
    - "web-search"
    - "web-fetch"
    - "file-write"
    - "file-read"

  instruction: |
    When the user requests deep research:
    1. Use web-search to find 5-10 relevant sources for the topic
    2. Use web-fetch to retrieve the content of each source
    3. Analyze and cross-reference the findings
    4. Identify areas of consensus and disagreement
    5. Use file-write to save the structured report
    6. Present a summary with confidence levels for each finding

    Always cite sources. Distinguish between primary research and commentary.
    If sources contradict each other, present both perspectives.

  input_schema:
    type: "object"
    properties:
      topic:
        type: "string"
        description: "The research topic"
      depth:
        type: "string"
        enum: ["quick", "standard", "exhaustive"]
        default: "standard"
      max_sources:
        type: "integer"
        default: 10
    required: ["topic"]

  output_schema:
    type: "object"
    properties:
      summary:
        type: "string"
      findings:
        type: "array"
        items:
          type: "object"
          properties:
            claim: { type: "string" }
            confidence: { type: "number", minimum: 0, maximum: 1 }
            sources: { type: "array", items: { type: "string" } }
      report_path:
        type: "string"

  permissions:
    network: true
    filesystem: "write-workspace"
    approval_required: false

  world_model_ref: "environment-model"

  estimates:
    avg_tokens: 15000
    avg_duration_seconds: 120
    avg_tool_calls: 25

---

Key Fields

Field	Required	Description
description	Yes	Human-readable description of what this skill accomplishes.
tools_required	Yes	List of tool names this skill depends on. All must be available at runtime.
instruction	Yes	Natural-language instructions for the LLM. The core of the skill — tells the LLM how to orchestrate the tools.
input_schema	No	JSON Schema for parameters the user provides when invoking the skill.
output_schema	No	JSON Schema describing the expected output structure.
permissions	No	Permission requirements (network, filesystem, approval). Enables security vetting before installation.
world_model_ref	No	Optional reference to a declared WorldModel used for predictive planning before action.
estimates	No	Estimated resource usage (tokens, duration, tool calls). Informational only.

---

Skill vs Tool

Dimension	Tool	Skill
Granularity	Atomic function	Composed workflow
Execution	Single invocation, deterministic	Multi-step, LLM-guided
Instructions	Parameter schema only	Natural language + schema
Dependencies	Standalone	Requires other tools
MCP equivalent	tools/call	No MCP equivalent

---

Validation Rules

• The description, tools_required, and instruction fields are REQUIRED.
• All tools listed in tools_required MUST exist in the manifest at runtime. If any are missing, the runtime MUST reject the skill activation.
• The instruction field MUST be a non-empty string.
• If world_model_ref is present, it MUST resolve to a declared WorldModel.

---

Design Rationale

The Skill primitive formalizes composed workflows with portable natural-language instructions. The instruction field travels with the skill definition, making skills reusable across runtimes. The permissions field enables security vetting before installation — a runtime can inspect what a skill needs before granting access. In CKP 0.3.0, a Skill can also reference a reusable WorldModel instead of embedding predictive logic directly in prompt text. There is no MCP equivalent for skills; this is a gap CKP fills.