Claude Skills: Recursive Dependencies or Portable Bundles?

Agent Skills should not be treated as mere folders of prompts. As soon as a skill contains instructions, scripts, templates, references, policies and operating procedures, it becomes a software module. And like any software module, it can have dependencies.

The critical point is this: if a skill X depends on a skill Y, and Y depends on Z, the agentic system must know how to manage that chain. Otherwise the agent risks running an incomplete procedure, improvising a missing part, or producing a plausible but incorrect output.

The Problem

A skill can depend on three different categories of components:

1. other skills
2. external tools
3. runtimes or execution environments

Example:

audit-solidity
 ├── solidity-static-analysis
 ├── report-generator
 ├── forge
 ├── slither
 └── python>=3.11

Here audit-solidity is not self-contained. It requires other skills, tools and runtimes. So installing the audit-solidity/ folder is not enough: you must ensure everything needed is present, compatible and authorised.

Option 1: Dependency Resolver

The first solution is to treat skills as software packages with explicit dependencies. Each skill has a machine manifest, e.g. skill.json, next to SKILL.md:

{
  "name": "audit-solidity",
  "version": "1.2.0",
  "dependencies": {
    "skills": [
      { "name": "solidity-static-analysis", "version": "^1.0.0" },
      { "name": "report-generator", "version": "^2.1.0" }
    ],
    "tools": ["forge", "slither", "solc"],
    "runtimes": ["python>=3.11"]
  },
  "capabilities": [
    "read-files",
    "write-files",
    "run-bash"
  ]
}

The system reads the manifest, builds the dependency graph and installs everything in the correct order:

install(audit-solidity)
  → install(solidity-static-analysis)
  → install(report-generator)
  → check forge
  → check slither
  → check python>=3.11
  → register audit-solidity

This approach requires a non-trivial infrastructure:

Skill Registry
Dependency Resolver
Compatibility Checker
Capability Checker
Installer
Runtime Loader
Policy Engine

Pros: modular updates, reuse of common skills, less duplication, an elegant and scalable model, well suited to development environments.

Cons: greater complexity, version-conflict handling, risk of missing dependencies, need for a reliable registry, less predictable installation. The resolver must also detect cycles (A → B → C → A) and version conflicts (one skill needs report-generator ^2.0.0, another ^3.0.0).

Option 2: Portable, Self-Contained Bundle

The second solution moves complexity from install time to export time. Instead of installing X and then recursively resolving Y and Z, whoever exports X produces an already-complete bundle:

audit-solidity.skillbundle/
├── bundle.json
├── lockfile.json
├── checksums.json
├── skills/
│   ├── audit-solidity/
│   ├── solidity-static-analysis/
│   └── report-generator/
├── assets/
├── policies/
└── tests/

The bundle.json declares what it contains and what stays external:

{
  "name": "audit-solidity-bundle",
  "version": "1.0.0",
  "root_skill": "audit-solidity",
  "contains": {
    "skills": [
      "audit-solidity@1.2.0",
      "solidity-static-analysis@1.0.4",
      "report-generator@2.1.3"
    ],
    "policies": [
      "audit-severity-policy@1.0.0"
    ],
    "assets": [
      "report-template-v3"
    ]
  },
  "requires_external": {
    "tools": ["forge", "slither", "solc"],
    "runtimes": ["python>=3.11"]
  }
}

The lockfile.json pins the included versions; checksums.json lets you verify the bundle has not been altered:

{
  "locked": [
    { "name": "audit-solidity", "version": "1.2.0", "hash": "sha256:..." },
    { "name": "report-generator", "version": "2.1.3", "hash": "sha256:..." }
  ]
}

Pros: predictable installation, reproducibility, suited to enterprise or offline environments, less reliance on remote registries, lower risk of missing skills at runtime.

Cons: heavier bundles, duplication of common skills, less granular updates, risk of divergent copies. The bundle need not include heavy runtimes like Python, Docker or Foundry: it can declare them as external requirements. But it should include all logical dependencies between skills.

The Best Model: Hybrid

The most robust solution uses both models at different moments:

Development:   dependency resolver
Distribution:  portable bundle
Execution:     policy engine + capability checker

In development, a registry that resolves dependencies modularly makes sense: updating common skills, testing different versions, composing complex workflows. In production, it is better to export portable, versioned, verifiable and reproducible bundles. The rule is simple:

Resolver to build.
Bundle to distribute.
Policy engine to run.

Conclusion

Skills bring modularity to the world of AI agents. But modularity without dependency management becomes fragility. A mature agentic platform must choose a clear strategy: recursively resolve dependencies, export self-contained bundles, or combine both approaches. The first option suits development, the second production, the third is the most solid model.

A skill should not be just a folder of prompts. It should be an operating package for agents: declarative, versioned, verifiable, testable and governable.