Skill IR reference

The Skill IR (Intermediate Representation) is the canonical, versioned JSON contract for any Claresia skill. The same Skill IR is consumed by the Distribution Plane to publish the skill into Claude Enterprise, Microsoft Copilot, ChatGPT Enterprise, and Slack — without per-platform authoring.

Schema location: Claresia - Roadmap/cc-065-microsoft-copilot-distribution/schema/skill-ir-v0.json

Current version: v0.4.0.

Top-level shape

{
  "$schema": "https://docs.claresia.com/schemas/skill-ir-v0.json",
  "skill_id": "gatespic.incident-postmortem",
  "skill_version": "1.4.2",
  "title": "Incident Postmortem",
  "description": "Generate a structured postmortem for a Gatespic-tracked incident, including timeline, root cause, impact, and remediation.",
  "function": "gatespic",
  "owner": "claresia",
  "ir_version": "v0.4.0",
  "archetypes": ["firmware_engineer", "eng_lead", "sre"],
  "system_prompt": "...",
  "parameters": [...],
  "tools": [...],
  "knowledge_sources": [...],
  "output_contract": {...},
  "telemetry": {...},
  "rbac": {...},
  "lifecycle": {...},
  "provenance": {...}
}

Required fields

Identity

• skill_id — globally unique, format <function>.<skill-name> in kebab-case
• skill_version — semver. Patch = bug fix, minor = additive, major = breaking
• title — human-readable, ≤ 60 chars
• description — 1–3 sentences, end-user visible (shown in @ picker)
• function — one of sailford, forge, boss, ledger, gatespic, takecare, steve, clawshield, zottos
• owner — claresia for shipped, customer:{tenant} for custom
• ir_version — IR schema version this skill conforms to
• archetypes — list of archetype IDs that should see this skill in their @ picker

Behavioral

• system_prompt — the LLM system prompt
• parameters — input parameters (typed, with descriptions)
• output_contract — the expected response shape
• telemetry — what to emit per invocation
• rbac — finer-grained scoping than archetypes
• lifecycle — state (draft, published, deprecated), deprecation date

parameters schema

{
  "parameters": [
    {
      "name": "incident_id",
      "type": "string",
      "required": true,
      "description": "The Gatespic incident ID, format INC-YYYY-MM-####",
      "validation": { "pattern": "^INC-\\d{4}-\\d{2}-\\d{4}$" }
    },
    {
      "name": "include_postmortem_template",
      "type": "boolean",
      "required": false,
      "default": true,
      "description": "Include the company-standard postmortem template in the prompt context"
    }
  ]
}

Supported types: string, number, integer, boolean, enum, date, datetime, array, object, file_ref, hub_record_ref.

tools schema

Tools the LLM can call mid-execution. Tool names map to platform-specific implementations (e.g., Anthropic Tool Use, OpenAI Functions, Copilot Studio Power Automate flows).

{
  "tools": [
    {
      "name": "fetch_incident",
      "description": "Fetch a Gatespic incident by ID",
      "input_schema": {
        "type": "object",
        "properties": { "incident_id": { "type": "string" } },
        "required": ["incident_id"]
      },
      "implementation": {
        "type": "http_endpoint",
        "method": "GET",
        "url": "https://api.gatespic.claresia.com/v1/incidents/{incident_id}",
        "auth": "tenant_api_key"
      }
    }
  ]
}

knowledge_sources schema

Reference material the skill grounds in:

{
  "knowledge_sources": [
    {
      "type": "static_file",
      "path": "skills/gatespic/postmortem-rubric.md",
      "scope": "always"
    },
    {
      "type": "hub_query",
      "query": {
        "tenant_id": "{{tenant_id}}",
        "record_type": "decision",
        "decision_subject": "incident_*"
      },
      "scope": "context_aware",
      "max_records": 50
    }
  ]
}

output_contract schema

{
  "output_contract": {
    "format": "markdown",
    "required_sections": [
      "Summary",
      "Timeline",
      "Root Cause",
      "Impact",
      "Remediation",
      "Lessons Learned"
    ],
    "max_tokens": 4000,
    "emit_hub_record": {
      "record_type": "output",
      "additional_fields": {
        "related_records": "{{tool_call_results.fetch_incident.related_record_ids}}"
      }
    }
  }
}

telemetry schema

{
  "telemetry": {
    "always_emit": ["skill_id", "skill_version", "user_id", "archetype_id",
                    "success", "latency_ms", "tokens_in", "tokens_out",
                    "cost_usd_estimate"],
    "extra": ["incident_id"],
    "redact_in_mode_c": ["incident_id"]
  }
}

rbac schema

{
  "rbac": {
    "default_archetypes": ["firmware_engineer", "eng_lead", "sre"],
    "blocklist_groups": ["claresia-restricted-no-pii"],
    "require_mfa_in_session": false,
    "require_decision_capture": false
  }
}

lifecycle schema

{
  "lifecycle": {
    "state": "published",
    "published_at": "2026-04-12T00:00:00Z",
    "deprecates": null,
    "deprecation_date": null,
    "successor_skill_id": null
  }
}

When you ship a v2 of a skill, the v1 IR’s lifecycle.deprecates points to v2, and v2’s successor_skill_id is set. Old v1 invocations are routed to v2 with a 30-day grace period before v1 is unpublished.

provenance schema

{
  "provenance": {
    "author": "claresia-engineering",
    "source_repo": "https://github.com/claresia/skills/gatespic/incident-postmortem",
    "source_commit": "a1b2c3d4",
    "validated_against_fixtures": "fixtures/gatespic-postmortem-v1.4.2.jsonl",
    "ir_hash": "sha256:..."
  }
}

Validating a Skill IR

# Install the validator
pip install claresia-skill-validator

# Validate against the schema
claresia-skill-validator validate path/to/skill.json

# Output:
# ✅ skill_id format
# ✅ semver
# ✅ archetypes referenced exist in cc-051 bundle
# ✅ tools referenced exist
# ✅ knowledge_sources exist
# ✅ output_contract complete
# ✅ ir_hash matches computed hash
# Skill IR is valid for IR v0.4.0

Cross-platform transpilation

The Distribution Plane reads the IR and emits per-platform implementations:

Platform	Output
Claude Enterprise	Anthropic Skill JSON
Microsoft Copilot M365	Copilot Studio agent YAML + Power Automate flow JSON
OpenAI ChatGPT Enterprise	Custom GPT bundle (ZIP)
Slack	Slack slash command + workflow definition

The transpiler is deterministic — same IR → same per-platform artifact bytes.

Versioning

• IR schema is versioned v0.x.0 until v1.0.0 GA
• Customers can pin a tenant to a specific IR version
• Breaking changes ship behind feature flags with 12-month deprecation
• Migration tools run at the contract layer (not in customer skills)