Custom Skill SDK

You can ship a tenant-specific skill by authoring its Skill IR, validating it locally, and publishing via Claresia’s Distribution Plane. The skill then appears in the @claresia picker for the archetypes you grant — across all four LLM platforms — without per-platform authoring.

SDK packages

Language	Package	Purpose
Python	`pip install claresia-skill-sdk`	Author + validate + test + publish
TypeScript	`npm install @claresia/skill-sdk`	Same
CLI	`npm install -g @claresia/skill-cli`	Validate, lint, publish, run-locally

All three share the same Skill IR JSON schema.

Hello-world skill in 5 minutes

1. Scaffold

claresia skill new dainese.weekly-summary
cd dainese.weekly-summary

Generates a folder with:

skill.json — the IR
prompts/system.md — the system prompt (referenced by IR)
tools/ — tool implementation stubs
fixtures/ — test fixtures
tests/ — pytest + node:test
README.md

2. Edit `skill.json`

{
  "skill_id": "dainese.weekly-summary",
  "skill_version": "0.1.0",
  "title": "Weekly Personal Summary",
  "description": "Summarize your week from your calendar, commits, and chat threads.",
  "function": "boss",
  "owner": "customer:dainese",
  "ir_version": "v0.4.0",
  "archetypes": ["firmware_engineer", "3d_product_manager", "fpa_analyst"],
  "system_prompt": "{{file: prompts/system.md}}",
  "parameters": [
    {
      "name": "week_of",
      "type": "date",
      "required": false,
      "default": "{{this_monday}}",
      "description": "Week start (Monday). Defaults to this week."
    }
  ],
  "tools": [
    {
      "name": "fetch_calendar_week",
      "description": "Fetch the user's calendar for the given week",
      "input_schema": {
        "type": "object",
        "properties": { "week_of": { "type": "string", "format": "date" } },
        "required": ["week_of"]
      },
      "implementation": {
        "type": "http_endpoint",
        "method": "GET",
        "url": "https://api.dainese.claresia.com/calendar/week/{week_of}",
        "auth": "tenant_api_key"
      }
    }
  ],
  "output_contract": {
    "format": "markdown",
    "required_sections": ["This week", "What I learned", "Next week", "Asks"],
    "max_tokens": 1500,
    "emit_hub_record": { "record_type": "output" }
  },
  "telemetry": {
    "always_emit": ["skill_id", "skill_version", "user_id", "archetype_id",
                    "success", "latency_ms", "tokens_in", "tokens_out", "cost_usd_estimate"],
    "extra": ["week_of"]
  },
  "rbac": { "default_archetypes": ["firmware_engineer", "3d_product_manager", "fpa_analyst"] },
  "lifecycle": { "state": "draft" },
  "provenance": { "author": "dainese-it-admin@dainese.it" }
}

3. Validate locally

claresia skill validate
# ✅ skill_id format
# ✅ semver
# ✅ archetypes referenced exist
# ✅ tools referenced exist
# ✅ output_contract complete
# Skill IR is valid for IR v0.4.0

4. Lint + best-practice checks

claresia skill lint
# ⚠️  Consider adding `validation` regex on the `week_of` parameter
# ⚠️  System prompt is 1,247 tokens — consider tightening (target <800)
# ✅ Other checks pass

5. Run locally with a test fixture

claresia skill run --fixture fixtures/week-of-2026-04-21.json
# Calls a local LLM (default: claude-haiku-4.5 via your ANTHROPIC_API_KEY)
# Renders the output to stdout
# Writes a synthetic Hub record to .claresia-local/hub/

6. Test with cross-language fixtures

pytest tests/
npm test
# Both must pass — provenance hashes must match byte-for-byte

7. Publish to your tenant (DRAFT first)

claresia skill publish --tenant dainese --state draft
# Skill uploaded to Claresia control plane
# Distribution Plane DOES NOT publish to LLM yet (state=draft)
# IT admin can preview in Command Center → Skills → Drafts

8. Promote to PUBLISHED

claresia skill promote --tenant dainese --skill dainese.weekly-summary --state published
# Distribution Plane publishes to all connected LLM platforms within 60s
# governance_event(skill.published) is emitted
# End users in granted archetypes see the skill in their @claresia picker

Versioning a skill

# After bug fix, bump patch:
claresia skill bump --patch  # 0.1.0 → 0.1.1

# After additive feature:
claresia skill bump --minor  # 0.1.1 → 0.2.0

# After breaking change:
claresia skill bump --major  # 0.2.0 → 1.0.0
# Major bumps require --deprecates <previous_version> + --successor for downgrade path

Implementing tools

Three tool implementations supported:

`http_endpoint`

Most common. Claresia routes the tool call through the customer’s tenant API (authentication: tenant API key, OAuth2 client credentials, or mTLS).

`power_automate_flow` (Mode A/B with Microsoft Copilot)

Tool call triggers a Power Automate flow in your claresia-{tenant} Power Platform environment.

`mcp_server`

Tool calls go to an MCP server you’ve registered with Claresia. Supports stdio + Streamable HTTP transports.

Knowledge sources

{
  "knowledge_sources": [
    { "type": "static_file", "path": "docs/dainese-firmware-rubric.md", "scope": "always" },
    { "type": "hub_query", "query": { "record_type": "decision", "decision_subject": "firmware_*" }, "scope": "context_aware", "max_records": 50 },
    { "type": "mcp_resource", "server": "dainese-jira", "uri": "jira://projects/FIRM/issues/recent" }
  ]
}

If you build a skill that would be valuable to other customers, you can contribute it to the Claresia catalog (subject to review):

claresia skill propose-public path/to/skill.json
# Submits to Claresia's public catalog review queue
# Reviewed within 5 business days
# If accepted, ships in the next public release as `community.<skill-name>`