Skip to content
DWS Specification

Spec 3: Skill Specification

DWS Spec 3: Skill Specification

Digital Worker Standard — DWS Specification

Version: 1.0 Tier: 1 — Core Primitive Status: Release Candidate Dependencies: Spec 1 (Worker Identity), Spec 4 (Intent Artifacts)

1. Overview

A skill is the composable unit of worker capability in DWS. It sits above the tool layer (MCP) and below the workflow layer (Spec 6). Where a tool is a single operation (“read file,” “call API”), a skill is a portable, versioned, verifiable unit of work that combines tools, decision logic, and context requirements into a reusable capability.

Skills are the building blocks that workers use to execute work. A worker’s capability declaration (Spec 1) is expressed as a list of skills it can execute. A workflow phase (Spec 6) specifies which skills are available during execution. The marketplace distributes skills as packaged, versioned units.

Design Principles

  • Composable. Skills combine with other skills through well-defined composition patterns.
  • Portable. A skill definition works across any DWS-compliant runtime.
  • Verifiable. Every skill declares its own success criteria, independent of task-level verification.
  • Tool-agnostic. Skills reference MCP tools by interface, not by implementation.

2. Skill Descriptor Schema

2.1 Identity

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["name", "version", "domain", "author", "description"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$"
    },
    "domain": {
      "type": "string",
      "description": "Primary domain (e.g. 'engineering', 'marketing', 'finance')."
    },
    "author": {
      "type": "string",
      "description": "Author or organisation that created this skill."
    },
    "description": {
      "type": "string"
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier (e.g. 'MIT', 'Apache-2.0', 'proprietary')."
    },
    "provenance": {
      "type": "object",
      "properties": {
        "origin": { "type": "string", "description": "Organisation or registry this skill originates from." },
        "repository": { "type": "string", "format": "uri" },
        "published_at": { "type": "string", "format": "date-time" }
      },
      "description": "Origin and publication metadata for marketplace distribution."
    }
  }
}

2.2 Capability Declaration

Every skill MUST declare its capabilities in both human-readable and machine-readable forms.

{
  "capability": {
    "summary": "Reviews code changes for correctness, style compliance, and potential issues.",
    "tags": ["code-review", "quality", "engineering", "static-analysis"]
  }
}

2.3 Input Schema

Skills declare their inputs as a JSON Schema. This enables validation before execution and compatibility checking during composition.

{
  "input": {
    "parameters": {
      "type": "object",
      "required": ["diff", "base_branch"],
      "properties": {
        "diff": { "type": "string" },
        "base_branch": { "type": "string" },
        "review_focus": {
          "type": "array",
          "items": { "type": "string", "enum": ["correctness", "style", "security", "performance"] },
          "default": ["correctness", "style"]
        }
      }
    },
    "context_requirements": [
      {
        "layer": "institutional",
        "entry_types": ["convention", "constraint"],
        "scope": { "domains": ["engineering"] },
        "required": true
      }
    ],
    "model_capabilities": {
      "tool_use": true,
      "structured_output": true,
      "min_context_window": 32000,
      "modalities": ["text", "code"],
      "reasoning_capability": "standard"
    }
  }
}

2.4 Output Schema

Skills declare what they produce. Output types reference artifact types where applicable.

{
  "output": {
    "artifacts": [
      { "type": "review_report", "required": true },
      { "type": "suggested_fixes", "required": false }
    ],
    "schema": {
      "type": "object",
      "required": ["findings", "summary", "verdict"],
      "properties": {
        "findings": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["file", "line", "severity", "description"],
            "properties": {
              "file": { "type": "string" },
              "line": { "type": "integer" },
              "severity": { "type": "string", "enum": ["critical", "warning", "advisory"] },
              "description": { "type": "string" },
              "suggested_fix": { "type": "string" }
            }
          }
        },
        "summary": { "type": "string" },
        "verdict": { "type": "string", "enum": ["approve", "request_changes", "comment"] }
      }
    }
  }
}

2.5 Verification Criteria

Skills MAY declare their own success criteria. These are distinct from task-level verification (Spec 8) and apply specifically to whether the skill executed correctly.

{
  "verification_criteria": [
    { "dimension": "completeness", "threshold": 0.8, "description": "All files in the diff were reviewed." },
    { "dimension": "consistency", "threshold": 0.9, "description": "Findings align with loaded conventions." }
  ]
}

Skill-level verification is evaluated by the runtime after skill execution completes. If skill verification fails, the runtime SHOULD retry the skill (up to the configured retry limit) before escalating to workflow-level failure handling.

3. Skill Execution Model

3.1 Steps

A skill’s execution is defined as an ordered sequence of steps. Each step is an atomic action.

Step types:

TypeDescription
tool_callInvokes an MCP-defined tool. The step includes a tool_uri and input mapping.
transformProcesses data using a defined transformation. Implementation-specific.
decisionEvaluates a condition and determines the next step.
delegateInvokes another skill. The step includes a skill_ref and input/output mappings.

Each step has:

  • name (required): human-readable step name
  • type (required): one of the step types above
  • input_mapping: maps step inputs from skill inputs or previous step outputs (JSONPath)
  • output_mapping: maps step outputs to the skill’s execution context (JSONPath)
  • timeout: ISO 8601 duration
  • fallback: retry count, fallback step, or fail-skill flag

3.2 Decision Points

Decision steps evaluate conditions against the current execution context to determine control flow.

{
  "name": "check_language",
  "type": "decision",
  "branches": [
    { "condition": { "field": "$.input.language", "operator": "eq", "value": "python" }, "next_step": "python_lint" },
    { "condition": { "field": "$.input.language", "operator": "eq", "value": "typescript" }, "next_step": "ts_lint" }
  ],
  "default_step": "generic_lint"
}

Branches are evaluated in order. The first matching condition determines the next step. If no condition matches, default_step is used. If no default_step is defined and no condition matches, the skill MUST fail.

3.3 Tool Invocations

Steps of type tool_call reference MCP tools by URI.

{
  "name": "fetch_diff",
  "type": "tool_call",
  "tool_uri": "mcp://github/get-pull-request-diff",
  "input_mapping": { "repository": "$.input.repository", "pull_request_number": "$.input.pr_number" },
  "output_mapping": { "diff_content": "$.result.diff" },
  "timeout": "PT30S"
}

Runtimes MUST validate that all referenced tools are available before skill execution begins. If a required tool is unavailable, the skill MUST NOT start and MUST emit a skill.failed event with reason tool_unavailable.

4. Skill Composition

4.1 Dependency Declarations

Skills MAY declare dependencies on other skills.

{
  "dependencies": [
    { "skill_name": "fetch-source", "version_constraint": ">=1.0.0 <2.0.0", "required": true },
    { "skill_name": "static-analysis", "version_constraint": ">=2.1.0", "required": false }
  ]
}

Required dependencies MUST be available in the runtime before the skill can execute.

4.2 Composition Patterns

Skills compose through three patterns: sequential (one after another), parallel (concurrent execution with a join strategy), and conditional (branching based on runtime data).

For parallel composition, the join field specifies when the composition proceeds: all (wait for all skills), any (proceed when any completes), n_of_m (proceed when N of M complete).

4.3 Conflict Rules

When two skills in a composition declare contradictory constraints (e.g., different min_context_window values), the more restrictive constraint wins. For enum constraints, the intersection of allowed values applies. If the intersection is empty, the composition is invalid and MUST be rejected at validation time.

5. Skill Lifecycle & Distribution

5.1 Versioning

Skills are definition-time artifacts and are git-native. Skill versions follow semantic versioning. Skill versions are git tags in the format {skill-name}/v{major}.{minor}.{patch}.

5.2 Publishing

Skills are packaged for distribution as a bundle:

{skill-name}/
  skill.json          # Skill descriptor (this spec)
  implementation/     # Implementation files (runtime-specific)
  tests/              # Validation tests
  README.md           # Human documentation
  CHANGELOG.md        # Version history

The skill.json descriptor is the portable part. The implementation/ directory is runtime-specific.

5.3 Override Mechanism

Organisations MAY override specific fields of a published skill without forking it. Overrides MUST NOT change the skill’s input or output schema (those are part of the public contract). Overrides MAY change context requirements, verification thresholds, step timeouts, and fallback behaviours.

5.4 Deprecation

{
  "deprecation": {
    "deprecated_at": "2026-06-01T00:00:00Z",
    "replacement_skill": "code-review-v2@1.0.0",
    "sunset_date": "2026-12-01T00:00:00Z"
  }
}

After deprecated_at, runtimes SHOULD emit a warning when the skill is loaded. After sunset_date, runtimes MUST refuse to execute the skill.

6. Key Design Decisions

DecisionResolutionRationale
Execution step complexityOrdered sequence with decision branches (not full DAG)A full DAG introduces complexity that most skills don’t need. Skills needing DAG-level complexity should compose multiple simpler skills.
Skill-level verificationSkills MAY declare their own criteriaCatches execution errors early, before workflow-level verification (Spec 8). Optional because simple skills may not need it.
Relationship to MCPSkills are a superset that use MCP toolsA skill is a higher-order concept: it combines tools with sequencing, context, and verification. MCP defines the tool interface; DWS defines how tools compose into capabilities.

7. References

  • MCP (Model Context Protocol) — Defines the tool interface layer that skills build upon.
  • Unix Philosophy — The design ethos of small, composable utilities. Skills follow this principle.
  • npm/pip Package Specifications — Versioning, dependency resolution, and distribution patterns.
  • Spec 1: Worker Identity — Worker capability declarations reference skills.
  • Spec 4: Intent Artifacts — Skill output types reference intent artifact schemas.
  • Spec 6: Workflow & Phases — Workflow phases specify available skills.
  • Spec 8: Verification Framework — Task-level verification is distinct from skill-level verification criteria.