@dot-skill/protocol 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharat Dudeja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/** Open .skill Protocol v0.4 — types, constants, and schemas. */
+export { PROTOCOL_VERSION, CONTAINER_VERSION, WORKFLOW_DIALECT_VERSION, MEDIA_TYPE, MANIFEST_MEDIA_TYPE, DEFAULT_SKILL_POLICY, } from "./types.js";
+export type { SkillCompileProfile, PackageSensitivity, ProvenanceMode, MintStatus, PermanenceAnchorKind, TrustProfile, InputSource, SensitivityLevel, AskWhen, SideEffectClass, CapabilityFallback, KnowledgeItemType, SteeringEffect, WorkflowStepKind, SkillRunStatus, RuntimeMode, CompletenessPart, GenerationUsage, JourneyProvenance, CompletenessReport, JsonSchema, ContentDigest, ProvenanceRef, InputSlot, OutputContract, CapabilityAdapterHint, CapabilityRequirement, SkillPermission, SkillPolicy, SkillDependency, MintRecord, CreationAttestation, PermanenceAnchor, SkillManifest, KnowledgeItem, SteeringConstraint, WorkflowStepBase, InstructStep, PromptStep, ToolStep, TransformStep, BranchStep, IterateStep, DelegateStep, CheckpointStep, HumanDecisionStep, VerifyStep, EmitStep, SubskillStep, WorkflowStep, Workflow, CompilationIssue, CompilationMapping, CompilationReport, SkillPackageFiles, SkillStepRecord, SkillRun, } from "./types.js";
+export { FORBIDDEN_AGENT_HOSTS, isValidAgentHost, } from "./source.js";
+export type { SectionType, SectionAuthor, CodeRef, Attachment, PersonRef, SkillSection, SteeringEvent, PromptVersion, AgentContext, SkillSource, SteeringVerb, CaptureFidelity, } from "./source.js";
+export { recipeToSkillSource } from "./recipe.js";
+export type { IngredientType, VisibilityIntent, RecipeIngredient, Recipe, Skill, } from "./recipe.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+/** Open .skill Protocol v0.4 — types, constants, and schemas. */
+export { PROTOCOL_VERSION, CONTAINER_VERSION, WORKFLOW_DIALECT_VERSION, MEDIA_TYPE, MANIFEST_MEDIA_TYPE, DEFAULT_SKILL_POLICY, } from "./types.js";
+export { FORBIDDEN_AGENT_HOSTS, isValidAgentHost, } from "./source.js";
+export { recipeToSkillSource } from "./recipe.js";

package/dist/recipe.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Skillerr-shaped Recipe types — product adapter, not protocol vocabulary.
+ *
+ * Open protocol uses SkillSource / SkillSection (see source.ts).
+ * Skillerr (and similar products) map recipe/ingredient/bake → SkillSource/compile.
+ */
+import type { GenerationUsage, JourneyProvenance } from "./types.js";
+import type { AgentContext, Attachment, CodeRef, PersonRef, PromptVersion, SectionType, SkillSource, SteeringEvent } from "./source.js";
+/** @deprecated Prefer SectionType from source.ts — kept for Skillerr adapters. */
+export type IngredientType = SectionType;
+export type VisibilityIntent = "private" | "publishable";
+export type { SteeringVerb, CaptureFidelity } from "./source.js";
+export type { CodeRef, Attachment, PersonRef, SteeringEvent, PromptVersion } from "./source.js";
+/** @deprecated Prefer SkillSection — Skillerr ingredient shape. */
+export interface RecipeIngredient {
+    id: string;
+    revision: number;
+    type: IngredientType;
+    title: string;
+    body: string;
+    attachments: Attachment[];
+    code_refs: CodeRef[];
+    sensitivity: VisibilityIntent;
+}
+/**
+ * @deprecated Prefer SkillSource.
+ * Recipe is Skillerr's capture document; adapters convert it before compile.
+ */
+export interface Recipe {
+    kind: "recipe";
+    id: string;
+    hash: string;
+    title: string;
+    summary?: string;
+    ingredients: RecipeIngredient[];
+    steering: SteeringEvent[];
+    prompts: PromptVersion[];
+    code_refs: CodeRef[];
+    parents: string[];
+    provenance: {
+        hosts: string[];
+        models: string[];
+        session_ids: string[];
+    };
+    visibility_intent: VisibilityIntent;
+    baked_at: string;
+    baker: PersonRef;
+    source_protocol_version: string;
+    generation_usage?: GenerationUsage;
+    journey_summary?: string;
+}
+/** @deprecated Legacy flat markdown skill export. Prefer SkillManifest / `.skill`. */
+export interface Skill {
+    kind: "skill";
+    id: string;
+    version: string;
+    title: string;
+    body: string;
+    sources: Array<{
+        kind: "ingredient" | "recipe" | "section";
+        id: string;
+        revision?: number;
+        hash?: string;
+    }>;
+    exported_at: string;
+    source_protocol_version: string;
+}
+/** Map a Skillerr Recipe into protocol SkillSource. */
+export declare function recipeToSkillSource(recipe: Recipe, overrides?: {
+    agent?: Partial<AgentContext>;
+    journey?: Partial<JourneyProvenance>;
+}): SkillSource;

package/dist/recipe.js

@@ -0,0 +1,73 @@
+/**
+ * Skillerr-shaped Recipe types — product adapter, not protocol vocabulary.
+ *
+ * Open protocol uses SkillSource / SkillSection (see source.ts).
+ * Skillerr (and similar products) map recipe/ingredient/bake → SkillSource/compile.
+ */
+import { isValidAgentHost } from "./source.js";
+function visibilityToSensitivity(v) {
+    return v === "publishable" ? "public" : "private";
+}
+/** Map a Skillerr Recipe into protocol SkillSource. */
+export function recipeToSkillSource(recipe, overrides = {}) {
+    const host = overrides.agent?.host ?? recipe.provenance.hosts[0];
+    if (!isValidAgentHost(host)) {
+        throw new Error("AI agent host required to adapt Recipe → SkillSource. Set a real host (e.g. cursor, claude), not human/cli.");
+    }
+    const sections = recipe.ingredients.map((ing) => ({
+        id: ing.id,
+        revision: ing.revision,
+        type: ing.type,
+        title: ing.title,
+        body: ing.body,
+        attachments: ing.attachments,
+        code_refs: ing.code_refs,
+        sensitivity: visibilityToSensitivity(ing.sensitivity),
+        authored_by: "agent",
+    }));
+    const journey = {
+        summary: overrides.journey?.summary ??
+            recipe.journey_summary ??
+            recipe.summary ??
+            `Human+AI work captured as recipe ${recipe.id}: ${recipe.title}`,
+        open_questions: overrides.journey?.open_questions,
+        decisions: overrides.journey?.decisions ??
+            recipe.ingredients.filter((i) => i.type === "decision").map((i) => i.title),
+        redacted: overrides.journey?.redacted ?? true,
+        sensitivity: overrides.journey?.sensitivity ??
+            (recipe.visibility_intent === "publishable" ? "public" : "shareable_redacted"),
+    };
+    const declaresInputs = recipe.ingredients.some((ing) => /\{\{[a-zA-Z_][a-zA-Z0-9_]*\}\}|<([A-Z][A-Z0-9_]+)>|\$\{[a-zA-Z_][a-zA-Z0-9_]*\}/.test(ing.body));
+    return {
+        kind: "skill_source",
+        id: recipe.id,
+        hash: recipe.hash,
+        title: recipe.title,
+        summary: recipe.summary,
+        intent: recipe.summary ?? recipe.title,
+        sections,
+        steering: recipe.steering,
+        prompts: recipe.prompts,
+        code_refs: recipe.code_refs,
+        parents: recipe.parents,
+        agent: {
+            host: host,
+            provider: overrides.agent?.provider,
+            model: overrides.agent?.model ?? recipe.provenance.models[0],
+            runtime: overrides.agent?.runtime,
+            deployment: overrides.agent?.deployment,
+            endpoint: overrides.agent?.endpoint,
+            session_ids: overrides.agent?.session_ids ?? recipe.provenance.session_ids,
+        },
+        journey,
+        generation_usage: recipe.generation_usage,
+        inputs_declared: declaresInputs ? "inferred" : "none",
+        sensitivity: visibilityToSensitivity(recipe.visibility_intent) === "public"
+            ? "public"
+            : "shareable_redacted",
+        created_at: recipe.baked_at,
+        actor: recipe.baker,
+        source_protocol_version: recipe.source_protocol_version,
+        source_refs: [{ product: "skillerr", kind: "recipe", id: recipe.id, hash: recipe.hash }],
+    };
+}

package/dist/source.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Protocol-native source for the skill compiler.
+ *
+ * Products (Skillerr, etc.) may use their own words (ingredient, recipe, bake).
+ * Adapters map those into SkillSource / SkillSection before compile.
+ */
+import type { GenerationUsage, JourneyProvenance, PackageSensitivity } from "./types.js";
+export type SectionType = "prompt" | "decision" | "architecture" | "diagram" | "integration" | "resource" | "reference" | "lesson" | "requirement" | "tradeoff" | "risk" | "question" | "implementation_note" | "config" | "correction_note" | "doc" | "message" | "handoff" | "code" | "intent" | "workflow_note";
+export type SectionAuthor = "agent" | "human_via_agent";
+export interface CodeRef {
+    forge?: string;
+    repo: string;
+    commit?: string;
+    path?: string;
+    range?: string;
+    pr?: number;
+}
+export interface Attachment {
+    id: string;
+    kind: "diagram" | "image" | "config" | "file" | "other";
+    title?: string;
+    content?: string;
+    uri?: string;
+    mediaType?: string;
+}
+export interface PersonRef {
+    id: string;
+    display_name?: string;
+}
+export type SteeringVerb = "affirm" | "correct" | "reject";
+export type CaptureFidelity = "exact" | "synthesize";
+export interface SkillSection {
+    id: string;
+    revision: number;
+    type: SectionType;
+    title: string;
+    body: string;
+    attachments: Attachment[];
+    code_refs: CodeRef[];
+    /** Never embed secret values — sensitivity guides redaction. */
+    sensitivity: PackageSensitivity;
+    /** Declared authoring path for this section. */
+    authored_by: SectionAuthor;
+}
+export interface SteeringEvent {
+    kind: "steering";
+    id: string;
+    session_id: string;
+    verb: SteeringVerb;
+    target_kind: "section" | "turn" | "other" | "ingredient";
+    target_id: string;
+    note?: string;
+    actor: PersonRef;
+    at: string;
+}
+export interface PromptVersion {
+    kind: "prompt";
+    id: string;
+    lineage_id: string;
+    version: number;
+    body: string;
+    origin: "user" | "ai_generated" | "imported";
+    parent_version?: number;
+    session_id?: string;
+    created_at: string;
+}
+/** Required AI agent identity for any compile path. */
+export interface AgentContext {
+    /** Host/app that ran the agent: cursor | ollama | lmstudio | custom-agent | … */
+    host: string;
+    /** Model provider/runtime family; provider-neutral and local-friendly. */
+    provider?: string;
+    model?: string;
+    runtime?: string;
+    /** Where inference ran. This is provenance, not proof. */
+    deployment?: "local" | "hosted" | "hybrid" | "unknown";
+    /** Optional endpoint identifier. Must not contain credentials. */
+    endpoint?: string;
+    session_ids?: string[];
+}
+/**
+ * Protocol input to the compiler.
+ * Products adapt their capture model into this shape.
+ */
+export interface SkillSource {
+    kind: "skill_source";
+    id: string;
+    hash: string;
+    title: string;
+    summary?: string;
+    intent?: string;
+    sections: SkillSection[];
+    steering: SteeringEvent[];
+    prompts: PromptVersion[];
+    code_refs: CodeRef[];
+    parents: string[];
+    agent: AgentContext;
+    journey: JourneyProvenance;
+    generation_usage?: GenerationUsage;
+    /** Explicitly declare that the source needs no runtime inputs. */
+    inputs_declared?: "inferred" | "none";
+    sensitivity: PackageSensitivity;
+    created_at: string;
+    actor: PersonRef;
+    source_protocol_version: string;
+    /** Optional product-specific source refs (e.g. Skillerr recipe id). */
+    source_refs?: Array<{
+        product: string;
+        kind: string;
+        id: string;
+        hash?: string;
+    }>;
+}
+/** Hosts that are not valid AI agent runtimes for skill creation. */
+export declare const FORBIDDEN_AGENT_HOSTS: Set<string>;
+export declare function isValidAgentHost(host: string | undefined | null): boolean;

package/dist/source.js

@@ -0,0 +1,20 @@
+/**
+ * Protocol-native source for the skill compiler.
+ *
+ * Products (Skillerr, etc.) may use their own words (ingredient, recipe, bake).
+ * Adapters map those into SkillSource / SkillSection before compile.
+ */
+/** Hosts that are not valid AI agent runtimes for skill creation. */
+export const FORBIDDEN_AGENT_HOSTS = new Set([
+    "",
+    "human",
+    "manual",
+    "none",
+    "cli",
+    "user",
+]);
+export function isValidAgentHost(host) {
+    if (!host)
+        return false;
+    return !FORBIDDEN_AGENT_HOSTS.has(host.trim().toLowerCase());
+}

package/dist/types.d.ts

@@ -0,0 +1,434 @@
+/** Open .skill Protocol v0.4 — semantic types for portable `.skill` packages. */
+export declare const PROTOCOL_VERSION = "0.4.0";
+export declare const CONTAINER_VERSION = "1.0";
+export declare const WORKFLOW_DIALECT_VERSION = "1.0";
+/** Media type for a packaged `.skill` archive (zip). */
+export declare const MEDIA_TYPE = "application/vnd.dot-skill+zip";
+/** Media type for the manifest JSON document inside a `.skill` archive. */
+export declare const MANIFEST_MEDIA_TYPE = "application/vnd.dot-skill-manifest+json";
+/**
+ * Compile profiles:
+ * - continuity: partial OK — portable AI work context / handoff (draft)
+ * - release: full requirements or refuse — reusable sealed skill
+ */
+export type SkillCompileProfile = "continuity" | "release";
+/** Package sharing intent — secrets never embedded either way. */
+export type PackageSensitivity = "private" | "shareable_redacted" | "public";
+export type ProvenanceMode = "full" | "redacted" | "proof_only";
+export type MintStatus = "draft" | "minted";
+export type PermanenceAnchorKind = "registry" | "transparency_log" | "ledger" | "content_addressed_store" | "other";
+export type TrustProfile = "open" | "minted" | "anchored" | `issuer:${string}`;
+export type InputSource = "human" | "environment" | "secret" | "artifact" | "derived";
+export type SensitivityLevel = "public" | "private" | "secret";
+export type AskWhen = "always" | "if_missing" | "never";
+export type SideEffectClass = "none" | "read" | "write" | "network" | "exec" | "destructive";
+export type CapabilityFallback = "fail" | "ask_human" | "skip_if_optional";
+export type KnowledgeItemType = "rule" | "principle" | "decision" | "tradeoff" | "correction" | "lesson" | "constraint" | "reference";
+export type SteeringEffect = "invariant" | "forbidden" | "decision_rule" | "approval_gate";
+export type WorkflowStepKind = "instruct" | "prompt" | "tool" | "transform" | "branch" | "iterate" | "delegate" | "checkpoint" | "human_decision" | "verify" | "emit" | "subskill";
+export type SkillRunStatus = "pending" | "running" | "paused" | "succeeded" | "failed" | "cancelled";
+export type RuntimeMode = "inspect" | "explain" | "dry_run" | "execute" | "resume";
+/** Parts the compiler checks before producing a package. */
+export type CompletenessPart = "agent_context" | "intent" | "sections" | "workflow" | "knowledge_or_prompts" | "inputs_declared" | "journey" | "generation_usage" | "human_approvals";
+export interface GenerationUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    reported_by: "agent" | "host" | "estimated";
+    captured_at: string;
+    host?: string;
+    model?: string;
+}
+/** Generalized human+AI journey — never raw chat / CoT / secrets. */
+export interface JourneyProvenance {
+    summary: string;
+    open_questions?: string[];
+    decisions?: string[];
+    redacted: boolean;
+    sensitivity: PackageSensitivity;
+}
+export interface CompletenessReport {
+    kind: "completeness_report";
+    profile: SkillCompileProfile;
+    complete: boolean;
+    present: CompletenessPart[];
+    missing: CompletenessPart[];
+    hints: string[];
+}
+/** JSON Schema subset stored as a plain object. */
+export type JsonSchema = Record<string, unknown>;
+export interface ContentDigest {
+    path: string;
+    digest: string;
+    media_type?: string;
+    bytes?: number;
+}
+export interface ProvenanceRef {
+    kind: "section" | "source" | "steering" | "author" | "legacy_skill" | "ingredient" | "recipe";
+    id: string;
+    revision?: number;
+    hash?: string;
+    note?: string;
+}
+export interface InputSlot {
+    name: string;
+    schema: JsonSchema;
+    description: string;
+    source: InputSource;
+    required: boolean;
+    default?: unknown;
+    sensitivity: SensitivityLevel;
+    ask_when: AskWhen;
+    examples?: unknown[];
+    provenance?: ProvenanceRef[];
+    generalization_reason?: string;
+    approved?: boolean;
+}
+export interface OutputContract {
+    name: string;
+    description?: string;
+    schema: JsonSchema;
+    required: boolean;
+    media_type?: string;
+    assert?: string[];
+}
+export interface CapabilityAdapterHint {
+    kind: "mcp" | "a2a" | "host" | "http";
+    name?: string;
+    uri?: string;
+    tool?: string;
+    meta?: Record<string, unknown>;
+}
+export interface CapabilityRequirement {
+    name: string;
+    description: string;
+    input_schema?: JsonSchema;
+    output_schema?: JsonSchema;
+    side_effect_class: SideEffectClass;
+    adapters?: CapabilityAdapterHint[];
+    fallback: CapabilityFallback;
+    required: boolean;
+}
+export interface SkillPermission {
+    side_effect_class: SideEffectClass;
+    description: string;
+    paths?: string[];
+    hosts?: string[];
+    requires_consent: boolean;
+}
+export interface SkillPolicy {
+    require_signatures: boolean;
+    require_minted?: boolean;
+    require_anchor?: boolean;
+    max_runtime_ms: number;
+    max_tool_calls: number;
+    allow_network: boolean;
+    filesystem_roots?: string[];
+    consent_for: SideEffectClass[];
+    fail_on_unsupported_step: boolean;
+    trust_profile?: TrustProfile;
+}
+export interface SkillDependency {
+    skill_id: string;
+    version: string;
+    package_digest?: string;
+}
+export interface MintRecord {
+    mint_status: MintStatus;
+    minted_at?: string;
+    mint_issuer?: string;
+    content_id?: string;
+}
+export interface CreationAttestation {
+    kind: "creation_attestation";
+    package_digest: string;
+    skill_id: string;
+    skill_version: string;
+    minted_at: string;
+    agent: {
+        runtime: string;
+        version: string;
+        key_id?: string;
+    };
+    host: string;
+    provider?: string;
+    model?: string;
+    deployment?: "local" | "hosted" | "hybrid" | "unknown";
+    endpoint?: string;
+    journey: {
+        /** @deprecated Prefer source_id — Skillerr recipe id when adapted. */
+        recipe_id?: string;
+        recipe_hash?: string;
+        source_id?: string;
+        source_hash?: string;
+        proof_digest?: string;
+        summary?: string;
+    };
+    generation_usage?: GenerationUsage;
+    human_approvals: {
+        inputs: string[];
+        permissions: string[];
+        actors: string[];
+    };
+    policy_profile?: TrustProfile;
+}
+export interface PermanenceAnchor {
+    kind: PermanenceAnchorKind;
+    package_digest: string;
+    located_at: string;
+    anchored_at: string;
+    issuer: string;
+    receipt?: unknown;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Manifest of a `.skill` package.
+ * Wire `kind` is `"dot-skill"`; the artifact extension is `.skill`.
+ */
+export interface SkillManifest {
+    kind: "dot-skill";
+    id: string;
+    version: string;
+    title: string;
+    description: string;
+    intent?: string;
+    triggers?: string[];
+    authors?: Array<{
+        id: string;
+        display_name?: string;
+    }>;
+    license?: string;
+    container_version: string;
+    protocol_version: string;
+    entrypoint: string;
+    inputs: InputSlot[];
+    outputs: OutputContract[];
+    capabilities: CapabilityRequirement[];
+    permissions: SkillPermission[];
+    policy: SkillPolicy;
+    content: ContentDigest[];
+    package_digest: string;
+    dependencies?: SkillDependency[];
+    supersedes?: string;
+    provenance_mode: ProvenanceMode;
+    /** continuity = handoff draft; release path may carry a signed attestation */
+    compile_profile?: SkillCompileProfile;
+    completeness?: CompletenessReport;
+    package_sensitivity?: PackageSensitivity;
+    mint?: MintRecord;
+    attestation_digest?: string;
+    anchors?: PermanenceAnchor[];
+    legacy?: boolean;
+    needs_human_review?: boolean;
+    extensions?: Record<string, Record<string, unknown>>;
+}
+export interface KnowledgeItem {
+    kind: "knowledge";
+    id: string;
+    type: KnowledgeItemType;
+    title: string;
+    body: string;
+    fidelity: "exact" | "synthesize";
+    applicability?: string;
+    pinned?: boolean;
+    sensitivity?: SensitivityLevel;
+    provenance?: ProvenanceRef[];
+}
+export interface SteeringConstraint {
+    kind: "steering_constraint";
+    id: string;
+    verb: "affirm" | "correct" | "reject";
+    effect: SteeringEffect;
+    statement: string;
+    source_steering_id?: string;
+    targets?: string[];
+    provenance?: ProvenanceRef[];
+}
+export interface WorkflowStepBase {
+    id: string;
+    kind: WorkflowStepKind;
+    title?: string;
+    optional?: boolean;
+    next?: string | string[];
+    on_fail?: string;
+    provenance?: ProvenanceRef[];
+}
+export interface InstructStep extends WorkflowStepBase {
+    kind: "instruct";
+    text: string;
+    knowledge_refs?: string[];
+}
+export interface PromptStep extends WorkflowStepBase {
+    kind: "prompt";
+    template: string;
+    input_bindings?: Record<string, string>;
+    knowledge_refs?: string[];
+}
+export interface ToolStep extends WorkflowStepBase {
+    kind: "tool";
+    capability: string;
+    arguments?: Record<string, unknown>;
+    argument_bindings?: Record<string, string>;
+    result_as?: string;
+}
+export interface TransformStep extends WorkflowStepBase {
+    kind: "transform";
+    expression: string;
+    input_from?: string;
+    result_as?: string;
+}
+export interface BranchStep extends WorkflowStepBase {
+    kind: "branch";
+    cases: Array<{
+        when: string;
+        goto: string;
+    }>;
+    else?: string;
+}
+export interface IterateStep extends WorkflowStepBase {
+    kind: "iterate";
+    over: string;
+    as: string;
+    body: string;
+}
+export interface DelegateStep extends WorkflowStepBase {
+    kind: "delegate";
+    agent_card?: string;
+    task: string;
+    result_as?: string;
+}
+export interface CheckpointStep extends WorkflowStepBase {
+    kind: "checkpoint";
+    message?: string;
+    require_human?: boolean;
+}
+export interface HumanDecisionStep extends WorkflowStepBase {
+    kind: "human_decision";
+    prompt: string;
+    choices?: string[];
+    result_as?: string;
+}
+export interface VerifyStep extends WorkflowStepBase {
+    kind: "verify";
+    assertions: string[];
+    against?: string;
+}
+export interface EmitStep extends WorkflowStepBase {
+    kind: "emit";
+    output: string;
+    from: string;
+}
+export interface SubskillStep extends WorkflowStepBase {
+    kind: "subskill";
+    skill_id: string;
+    version?: string;
+    input_bindings?: Record<string, string>;
+}
+export type WorkflowStep = InstructStep | PromptStep | ToolStep | TransformStep | BranchStep | IterateStep | DelegateStep | CheckpointStep | HumanDecisionStep | VerifyStep | EmitStep | SubskillStep;
+export interface Workflow {
+    kind: "workflow";
+    dialect_version: string;
+    entrypoint: string;
+    steps: WorkflowStep[];
+    constraints?: SteeringConstraint[];
+}
+export interface CompilationIssue {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    related?: string[];
+}
+export interface CompilationMapping {
+    from: ProvenanceRef;
+    to: {
+        kind: "knowledge" | "step" | "input" | "output" | "constraint";
+        id: string;
+    };
+}
+export interface CompilationReport {
+    kind: "compilation_report";
+    skill_id: string;
+    /** Protocol source id. */
+    source_id?: string;
+    /** @deprecated Skillerr adapter field — use source_id. */
+    recipe_id?: string;
+    profile: SkillCompileProfile;
+    created_at: string;
+    mappings: CompilationMapping[];
+    inferred_inputs: InputSlot[];
+    issues: CompilationIssue[];
+    pending_approvals: string[];
+    approved: boolean;
+    completeness: CompletenessReport;
+}
+export interface SkillPackageFiles {
+    manifest: SkillManifest;
+    workflow: Workflow;
+    knowledge: KnowledgeItem[];
+    prompts?: Record<string, string>;
+    resources?: Record<string, Uint8Array | string>;
+    artifacts?: Record<string, Uint8Array | string>;
+    provenance?: {
+        /** Scrubbed SkillSource or product source (never secrets). */
+        source?: unknown;
+        /** @deprecated Prefer source — Skillerr recipe blob. */
+        recipe?: unknown;
+        journey?: JourneyProvenance;
+        generation_usage?: GenerationUsage;
+        proof?: unknown;
+        compilation_report?: CompilationReport;
+    };
+    signatures?: Record<string, unknown>;
+    attestation?: CreationAttestation;
+    anchors?: PermanenceAnchor[];
+}
+export interface SkillStepRecord {
+    step_id: string;
+    kind: WorkflowStepKind;
+    status: "pending" | "skipped" | "succeeded" | "failed" | "waiting";
+    started_at?: string;
+    finished_at?: string;
+    input_digest?: string;
+    output_digest?: string;
+    adapter?: CapabilityAdapterHint;
+    approval?: {
+        actor: string;
+        at: string;
+        decision: "allow" | "deny";
+    };
+    error?: string;
+}
+export interface SkillRun {
+    kind: "skill_run";
+    id: string;
+    skill_id: string;
+    skill_version: string;
+    package_digest: string;
+    status: SkillRunStatus;
+    mode: RuntimeMode;
+    resolved_inputs: Record<string, unknown>;
+    secret_refs?: Record<string, string>;
+    steps: SkillStepRecord[];
+    outputs?: Record<string, unknown>;
+    verifications: Array<{
+        assertion: string;
+        passed: boolean;
+        detail?: string;
+    }>;
+    runtime: {
+        name: string;
+        version: string;
+        host?: string;
+        model?: string;
+    };
+    checkpoints?: Array<{
+        id: string;
+        step_id: string;
+        at: string;
+        state_digest: string;
+    }>;
+    started_at: string;
+    finished_at?: string;
+    error?: string;
+}
+export declare const DEFAULT_SKILL_POLICY: SkillPolicy;

package/dist/types.js

@@ -0,0 +1,19 @@
+/** Open .skill Protocol v0.4 — semantic types for portable `.skill` packages. */
+export const PROTOCOL_VERSION = "0.4.0";
+export const CONTAINER_VERSION = "1.0";
+export const WORKFLOW_DIALECT_VERSION = "1.0";
+/** Media type for a packaged `.skill` archive (zip). */
+export const MEDIA_TYPE = "application/vnd.dot-skill+zip";
+/** Media type for the manifest JSON document inside a `.skill` archive. */
+export const MANIFEST_MEDIA_TYPE = "application/vnd.dot-skill-manifest+json";
+export const DEFAULT_SKILL_POLICY = {
+    require_signatures: false,
+    require_minted: false,
+    require_anchor: false,
+    max_runtime_ms: 600_000,
+    max_tool_calls: 200,
+    allow_network: false,
+    consent_for: ["write", "network", "exec", "destructive"],
+    fail_on_unsupported_step: true,
+    trust_profile: "open",
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dot-skill/protocol",
+  "version": "0.4.1",
+  "description": "Open .skill Protocol — types, SkillSource, completeness",
+  "license": "MIT",
+  "author": {
+    "name": "Bharat Dudeja",
+    "url": "https://github.com/bharatdudeja13-cmd"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dot-skill/dot-skill.git",
+    "directory": "packages/protocol"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepack": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  }
+}