Skip to main content

Dependencies

Skillsmith tracks what skills depend on, detects when they change, and reports what's missing. This is powered by dependency intelligence — a system that combines declared metadata with automated content analysis.

How It Works

Dependency intelligence draws from three signal sources:

Declared — The skill author writes a dependencies block in SKILL.md frontmatter. Confidence: 1.0. This is the authoritative source.

Inferred (static) — At install time, Skillsmith scans skill content for mcp__server__tool patterns. References in prose get confidence 0.9; references inside code blocks get 0.5 (they may be illustrative examples).

Inferred (co-install) — (coming soon) The schema exists (inferred_coinstall source) but is not yet populated with behavioral data.

No auto-resolution — Skillsmith surfaces intelligence for awareness. Hard dependencies block installs; soft and inferred produce advisory warnings. Skillsmith never installs dependencies on your behalf.

For the engineering story behind this design, read Dependency Intelligence: How Skillsmith Infers What Your Skills Need.

Declaring Dependencies

Frontmatter Example

Add a dependencies block to your SKILL.md frontmatter. All sections are optional: 

---
name: my-skill
description: Example skill with full dependency declaration
dependencies:
  skills:
    - name: author/base-skill
      version: "^1.0.0"
      type: hard
      reason: Required for data formatting
    - name: author/helper-skill
      type: soft
      reason: Enhances output quality
    - name: author/companion-skill
      type: peer
  platform:
    cli: ">=1.5.0"
    mcp_servers:
      - name: linear
        package: "@anthropic/linear-mcp"
        required: true
      - name: github
        required: false
  models:
    minimum: claude-sonnet-4-20250514
    capabilities:
      - tool_use
      - extended_thinking
    context_window: 128000
  environment:
    tools:
      - name: docker
        required: true
        check: "docker --version"
      - name: git
        required: true
        check: "git --version"
    os:
      - darwin
      - linux
    node: ">=20.0.0"
  conflicts:
    - name: author/incompatible-skill
      reason: Conflicting CLAUDE.md modifications
---

Dependency Types

Type Category Behavior
skill_hard Skill Blocks install if missing
skill_soft Skill Warning at install, advisory
skill_peer Skill Expected co-install
mcp_server Platform Warning if not configured
cli_version Platform CLI version constraint
model_minimum Model Minimum model requirement
model_capability Model Required capability (e.g. tool_use)
env_tool Environment External tool (docker, git)
env_os Environment OS constraint
env_node Environment Node.js version constraint
conflict Conflict Must not coexist

Migrating from composes

The legacy composes field is deprecated. Migrate to dependencies.skills: 

# Before (deprecated)
---
composes:
  - author/helper-skill
---

# After
---
dependencies:
  skills:
    - name: author/helper-skill
      type: soft
      reason: Enhances output formatting
---

The skill_validate tool warns when it detects the deprecated composes field.

Tools

Seven MCP tools surface dependency intelligence. Each section shows the relevant response fields and tier requirements.

install_skill

Extracts and persists dependencies at install time. Hard dependencies block install with an error; soft and inferred produce warnings.

Response fields added by dependency intelligence:

{
  "dep_inferred_servers": ["linear", "github"],
  "dep_declared": {
    "skills": [
      { "name": "author/base-skill", "type": "hard", "reason": "Required for data formatting" }
    ],
    "platform": {
      "mcp_servers": [
        { "name": "linear", "package": "@anthropic/linear-mcp", "required": true }
      ]
    }
  },
  "dep_warnings": [
    "MCP server 'github' is referenced but may not be configured"
  ]
}

Community

get_skill

Returns the full dependency table as an array. Each entry includes the type, target, version constraint, source, and confidence score. 

{
  "dependencies": [
    {
      "dep_type": "skill_hard",
      "dep_target": "author/base-skill",
      "dep_version": "^1.0.0",
      "dep_source": "declared",
      "confidence": 1.0
    },
    {
      "dep_type": "mcp_server",
      "dep_target": "github",
      "dep_version": null,
      "dep_source": "inferred_static",
      "confidence": 0.9
    }
  ]
}

Community

skill_validate

Runs three dependency-related validations:

  1. Deprecated composes field — suggests migrating to dependencies.skills
  2. Undeclared MCP servers — detects mcp__server__tool patterns in skill prose and suggests declaring them in dependencies.platform.mcp_servers
  3. Both can fire simultaneously on the same skill
{
  "errors": [
    {
      "field": "composes",
      "message": "'composes' is deprecated. Migrate to 'dependencies.skills' with type: hard/soft/peer.",
      "severity": "warning"
    },
    {
      "field": "dependencies",
      "message": "Inferred MCP dependency: 'linear' (referenced in skill body). Consider declaring in dependencies.platform.mcp_servers.",
      "severity": "warning"
    }
  ]
}

Community

skill_outdated

Hash-based change detection compares installed content against the latest registry state. When include_deps is true (default), each skill includes dependency satisfaction status. 

{
  "skills": [
    {
      "id": "author/my-skill",
      "installed_hash": "a1b2c3d4",
      "latest_hash": "e5f6g7h8",
      "status": "outdated",
      "semver": "1.2.0",
      "dependencies": {
        "total": 3,
        "satisfied": ["skill_hard:author/base-skill", "mcp_server:linear"],
        "missing": ["skill_soft:author/helper-skill"]
      }
    }
  ],
  "summary": {
    "total_installed": 5,
    "outdated": 1,
    "up_to_date": 3,
    "unknown": 1,
    "missing_deps": 1
  }
}

Skill-type dependencies (skill_hard, skill_soft, skill_peer) are checked against your installed skills. Other types (MCP servers, models, environment) are marked satisfied as advisory — they cannot be reliably verified locally.

Community

skill_diff

Surfaces dependency section changes between two versions of a skill, shown in a side-by-side diff format.

Individual — requires version_tracking feature flag

skill_compare

Includes dependency counts in side-by-side skill comparison. "Fewer dependencies" is used as a recommendation reason when comparing similar skills.

Community

skill_audit

Security advisories complement dependency intelligence by checking for known vulnerabilities in skill dependencies. See Security for the full scanning model.

Team — requires skill_security_audit feature flag

Confidence Scoring

Source Confidence Meaning
Declared (frontmatter) 1.0 Author explicitly stated
Inferred prose 0.9 High-confidence MCP pattern in instruction text
Inferred code block 0.5 MCP pattern inside code fence (may be illustrative)

When both declared and inferred sources identify the same dependency, the declared entry wins and the inferred duplicate is dropped.

Tier Requirements

Tool Tier Feature Flag
install_skill Community —
get_skill Community —
skill_validate Community —
skill_outdated Community —
skill_compare Community —
skill_diff Individual version_tracking
skill_audit Team skill_security_audit

Limitations

  • Co-install inference: The inferred_coinstall source exists in the schema but is not yet populated
  • Semver range validation: Version constraints are stored but not enforced at install time
  • No automatic resolution: Skillsmith never installs dependencies on your behalf
  • No CycloneDX AI-BOM export: Dependency data is not yet exportable in standard SBOM formats
  • No dependency_policy configuration: You cannot configure per-project dependency rules

Related Documentation