SPEC-013 — Skills as Artifacts

Skills are versioned, lintable, swappable artifacts loaded by the runtime — not hardcoded modules.

Source: docs/design/spec-013-skills-as-artifacts.md

SPEC-013 — Skills as Artifacts

Field Value
Status Draft v1
Owner kris.ganjam@gmail.com
Date 2026-04-29
Depends on SPEC-001, SPEC-002
Pillar Forge
External standard https://agentskills.io/home

TL;DR

Skills are first-class artifacts. They live in-repo as files with substrate metadata, evolve through signals (votes, usage, calibration), get debated, link to other artifacts, and accumulate value through collective intelligence. SciDEX is the artifact ecosystem for science; skills become living, ranked, evolving units of agent know-how rather than static .md files. The substrate ingests external skills (k-dense, agentskills.io), authors native skills, and supports composed knowledge skills that draw on substrate state at runtime.

1. Goals

  • Skills are artifacts. Every property of an artifact — versions, history, signals, links, comments, supersession, lifecycle, federation — applies to skills automatically.

  • Three sources unified under one type: imported (external standards), native (built in scidex), composed (substrate-aware knowledge skills).

  • Open standard compatibility: a scidex skill can be exported as agentskills.io-compatible; an agentskills.io skill can be imported as a scidex skill.

  • Evolution: signals drive which skills surface in agent context. Top skills get more usage; bottom skills get deprecated.

  • Collective intelligence: skills can reference substrate state — “find similar failed hypotheses” returns LIVE data, not a frozen example.

2. Non-goals (this spec)

  • Replacing Claude Code’s built-in skills. SciDEX skills are additive; agents see both.

  • Forcing every existing skill into the substrate. Static-only skills can stay external; the substrate is opt-in for evolution.

  • Defining a new skill execution runtime. Skills run in the agent’s MCP context as instructions; tools (separate artifact type) provide execution. See SPEC-002.

3. The skill artifact type

{
  "type": "skill",
  "schema_version": 1,
  "id_strategy": { "format": "skill-{slug}", "stable": true },
  "lock_mode": "content_hash",
  "mutability": "mutable_with_history",
  "content_schema": {
    "type": "object",
    "required": ["name", "description", "instructions"],
    "properties": {
      "name": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]*$",
        "description": "Stable slug, agentskills.io-compatible"
      },
      "version": {
        "type": "string",
        "pattern": "^\\d+\\.\\d+\\.\\d+$",
        "description": "Semver"
      },
      "description": {
        "type": "string",
        "minLength": 20,
        "description": "Short summary surfaced in skill discovery"
      },
      "instructions": {
        "type": "string",
        "description": "SKILL.md content (markdown). Source-of-truth for agent context."
      },
      "triggers": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Plain-English triggers for skill discovery"
      },
      "tags": { "type": "array", "items": { "type": "string" } },
      "personas": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Persona slugs this skill is most useful for"
      },
      "inputs":  { "type": "object", "description": "JSON Schema for inputs" },
      "outputs": { "type": "object", "description": "JSON Schema for outputs" },
      "dependencies": {
        "type": "object",
        "properties": {
          "tools":       { "type": "array", "items": { "type": "string" } },
          "skills":      { "type": "array", "items": { "type": "string" } },
          "mcp_servers": { "type": "array", "items": { "type": "string" } }
        }
      },
      "examples": { "type": "array" },
      "files": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "path":   { "type": "string" },
            "sha256": { "type": "string" }
          }
        },
        "description": "Bundle files (relative to skill root)"
      },
      "source":        { "enum": ["native", "imported", "composed"] },
      "source_format": { "enum": ["scidex", "agentskills_io", "kdense", "claude_skill"] },
      "source_url":    { "type": "string" },
      "requires_substrate_access": {
        "type": "boolean",
        "default": false,
        "description": "True if skill calls scidex.* verbs at runtime (knowledge skill)"
      },
      "agentskills_io_compat": { "type": "boolean", "default": false }
    }
  },
  "links": {
    "uses_tool":          { "to_types": ["tool"] },
    "uses_skill":         { "to_types": ["skill"] },
    "derives_from":       { "to_types": ["skill"] },
    "documents_artifact": { "to_types": ["*"] },
    "supersedes":         { "to_types": ["skill"] }
  },
  "signals": {
    "vote":        { "values": [-1, 1], "aggregation": "replace" },
    "rank":        { "dimensions": ["clarity", "accuracy", "scope", "novelty"], "value_range": [0, 1], "aggregation": "replace" },
    "usage_count": { "aggregation": "sum", "auto": true },
    "calibration": { "metric": "completion_rate", "aggregation": "append" },
    "fund":        { "currency": "scidex_token", "aggregation": "sum" }
  },
  "lifecycle": {
    "states": ["draft", "active", "deprecated", "archived"],
    "transitions": [
      ["draft", "active"],
      ["active", "deprecated"],
      ["deprecated", "archived"],
      ["*", "archived"]
    ]
  },
  "validators": ["skill_name_unique", "skill_dependencies_resolve", "agentskills_io_compat_check"],
  "search": {
    "searchable": true,
    "embedding_recipe": "name + '\\n' + description + '\\n' + triggers[*] + '\\n' + instructions",
    "tsvector_recipe": "name || ' ' || description || ' ' || (triggers || ' ')",
    "boosts": { "name": 2.0, "triggers": 1.5 }
  }
}

4. Storage: hybrid (DB + filesystem)

Skills are multi-file bundles. Storage is hybrid:

  • DB: artifact row holds name, description, instructions (the full SKILL.md), metadata, signals.

  • Filesystem: supporting files (helpers.py, examples.json, etc.) live in the substrate repo at skills/<name>/.

  • Cross-reference: artifact content.files[] records (path, sha256) for each file; filesystem path resolves to skills/<name>/<path>.

This mirrors how wiki pages already work: slug + content_md in DB; supporting assets on disk.

When an agent loads a skill, it gets the instructions from the DB (canonical, versioned) and can fetch supporting files via a per-skill route (/api/scidex/skill/<name>/files/<path>).

5. Three sources

5.1 Imported (external standards)

External skills (agentskills.io, k-dense, claude-skills) imported via:

scidex skill import --kdense ~/k-dense-bundles/foo
scidex skill import --agentskills-io https://agentskills.io/s/bar
scidex skill import --claude-skill ~/.claude/skills/baz

Process:

  1. Read the external bundle’s manifest.

  2. Translate to scidex skill schema (provider-specific adapter).

  3. Copy files to skills/<name>/ in scidex-substrate repo.

  4. Create skill artifact with source: imported, source_format, source_url.

  5. Subsequent upstream releases trigger optional re-imports (manual or scheduled).

Local edits create a fork: a new skill artifact with derives_from link to the imported one.

5.2 Native (scidex-authored)

Skills authored directly in the substrate repo:

skills/find-similar-failed-hypotheses/
├── SKILL.md
├── examples.json
└── helpers.py

scidex skill register skills/find-similar-failed-hypotheses/ reads SKILL.md frontmatter + body, extracts metadata, registers as skill artifact with source: native.

5.3 Composed / knowledge skills

Skills that call substrate verbs at runtime to surface live data:

---
name: scidex_recent_hypotheses_in_pathway
description: Lists recent high-scoring hypotheses for a pathway, with evidence
triggers:
  - "user asks about hypotheses in pathway X"
  - "synthesizer needs candidate hypotheses for pathway Y"
requires_substrate_access: true
inputs:
  pathway:
    type: string
---

Search the substrate:

    hypotheses = scidex.search(
        types=["hypothesis"],
        filter={ "==": [{"var": "content.target_pathway"}, args["pathway"]] },
        sort=[("content.composite_score", "DESC")],
        limit=20
    )

For each, fetch supporting evidence:

    for h in hypotheses.items:
        evidence = scidex.links(ref=h.ref, predicates=["supports"])
        ...

Return a structured summary.

These are the most powerful kind of skill: they evolve not just because the skill itself is updated, but because the data they surface evolves with the substrate.

6. agentskills.io compatibility

The skill schema is a superset of agentskills.io fields. A scidex skill is exportable as agentskills.io-compatible if:

  • name, description, version present

  • instructions (mapped to agentskills.io’s body field)

  • triggers, inputs, outputs declared

  • File bundle structure matches

scidex skill export --format agentskills-io <skill-ref> produces the standard bundle.

agentskills_io_compat_check validator verifies a skill conforms before export.

7. Signals and evolution

Skills evolve through signals:

Signal kind Source Effect
vote User UI vote Up/down weight in discovery
rank Reviewer ratings (clarity/accuracy/scope/novelty) Quality score
usage_count Substrate auto-emits on each invocation Popularity
calibration Post-use measurement (did the declared outcome happen?) Trustworthiness
fund Researcher commits scidex_token for development Investment signal

A skill’s quality_score is a function of these signals (TBD weighting; declared in schema’s aggregation views).

Discovery surfacing: scidex.search(types=["skill"], ...) ranks results by a combined score. High-vote + high-calibration + high-usage = top. Decay over time prevents stale skills from dominating.

Deprecation: skills with low signals over a window auto-transition to deprecated state via a Senate-driven driver. Deprecated skills are still loadable but lose discovery priority.

Supersession: a new skill can claim to replace an older one via links.supersedes. The old skill’s superseded_by is set; usage redirects to the new one.

8. Skill discovery for agents

When an agent starts a task:

  1. Substrate constructs a query from task context (description, persona, recent activity).

  2. scidex.search(types=["skill"], query=task_summary, mode="hybrid", limit=K).

  3. Filter by triggers match, persona compatibility, dependency availability.

  4. Inject top-K skills into agent’s MCP context.

  5. Substrate emits skill.invoked event when the agent uses one.

Pre-loading by persona is also supported: agents with persona=skeptic get skill.tags includes 'skeptic' skills loaded by default.

9. Knowledge skills (substrate-aware)

A skill marked requires_substrate_access: true can:

  • Call any read-only substrate verb (get, list, search, links, signals, subscribe).

  • Aggregate live data into agent context.

  • Reference specific artifacts (paper:PMID:12345, hypothesis:h-abc) for grounding.

  • Subscribe to events for streaming knowledge (“alert me when new α-syn hypotheses score >0.8”).

These skills are the substrate’s collective-intelligence interface. As more artifacts accumulate, knowledge skills become more powerful without their own code changing.

Auth: knowledge skills run with the invoking agent’s permissions. They can’t bypass authorization.

10. Relationship to other skill ecosystems

Ecosystem Relationship
Claude Code built-in skills Coexist. Agent context includes both substrate and built-in skills.
Plugin marketplace skills (/plugin install) Coexist. May be imported into substrate for evolution if useful.
k-dense bundles Imported as substrate skills with source_format: kdense.
agentskills.io Bidirectional: import from URL, export native skills as compatible bundles.
MCP skills (server-side tools) Different layer. MCP servers expose tools; substrate skills are guidance about how to use those tools.

11. Skills and the Forge runtime

SPEC-002’s tool artifact type and SPEC-013’s skill are distinct but composable:

Aspect tool (SPEC-002) skill (SPEC-013)
What Runtime executable Agent-loadable instructions
Where it runs Forge sandbox (bwrap, GPU) In agent’s MCP context
Trigger scidex.gpu.submit(tool=name, args=…) scidex.search(types=['skill'], …) then loaded
Output tool_call artifact Agent’s task continuation

A skill can declare dependencies.tools: ["alphafold_predict"]. When the agent uses the skill, the substrate verifies the tool exists; the skill instructs the agent on how to use it.

A tool can be documented by a skill (links.documents_artifact: tool:alphafold_predict).

12. Migration path

# Title Scope Risk
K1 skill artifact type registered in schema_registry New schema; depends on SPEC-001 PR 5. Low
K2 skills/ directory in scidex-substrate Folder for native skills. Low
K3 scidex skill register CLI Reads SKILL.md, creates artifact. Low
K4 First native skill: skills/scidex/ (substrate-onboarding) The SKILL.md a new agent reads to understand the substrate. Low
K5 k-dense importer One-shot script + scheduled re-import. Medium
K6 agentskills.io importer/exporter Per the open standard. Medium
K7 Skill-discovery integration into MCP server Top-K skills loaded based on task context. Medium
K8 Skill signals: usage_count auto-emission Substrate emits on skill.invoked event. Low
K9 Calibration tracking Measure skill outcomes vs declared completion rate. Medium
K10 Skill quality score view Aggregation view over signals. Low
K11 Knowledge-skill execution path Skills with requires_substrate_access run scoped to agent permissions. Medium
K12 Forks and supersession UI/verbs for skill evolution. Low

Cadence: K1-K4 in week 1. K5-K7 weeks 2-3. K8-K12 weeks 4-6.

13. Why this matters

Static skill libraries codify what worked yesterday. Living skills let practice evolve as data accumulates and as agents discover better methods. In a substrate where artifacts evolve, skills must evolve too — otherwise the substrate’s collective intelligence outruns its agent capability.

Skills as artifacts is the substrate eating its own dogfood: the substrate provides agents the means to use it well, and those means evolve with the same machinery (signals, debates, supersession) as the science.

14. Open questions

  1. Native skill content storage canonicalness: file or DB? When a contributor edits SKILL.md on disk, what triggers the artifact update — git hook, file watcher, manual scidex skill register --update? Default: manual register; future automation via watcher.

  2. Skill dependency resolution at load time: if a skill depends on tool X but X isn’t available, do we still load the skill or omit it? Probably load with a flag.

  3. Cross-skill conflicts: two skills triggered by the same task with conflicting instructions. Prioritization? Probably highest quality_score wins; both surface as candidates.

  4. Skill-of-skills (composition): a skill that bundles multiple sub-skills. Supported via dependencies.skills; runtime concatenates instructions or selects by sub-context.

  5. Privacy: are skills public by default? Yes for native; imported follows source license; composed may surface private data — must respect agent permissions at runtime.

  6. Versioning of supporting files: when a skill’s helpers.py changes but instructions doesn’t, does that bump the skill version? Yes — file hash mismatch counts as a content change.

  7. agentskills.io URL stability: imported skills from external URLs; what happens when the URL goes 404? Substrate retains the imported copy; lifecycle becomes self-managed.

15. Interaction with other specs

  • SPEC-001: skills are a registered type; signals/links/events apply uniformly.

  • SPEC-002: tools and skills are distinct artifact types; they compose.

  • SPEC-005: skills are searchable; instructions are embedded for semantic discovery.

  • SPEC-009: the skill schema can evolve like any other.

  • SPEC-011: skills are publishable to ATProto / federable across instances.

  • SPEC-014: native skills live in the new scidex-substrate repo.