Introduction
Skills are filesystem-based packages that extend an AI agent's capabilities with domain-specific expertise.
As the skill ecosystem grows, an architectural challenge emerge: how skills should depend on each other. This post explores this challenge openly.
The Modularity Problem
Consider a tabular-review skill that performs due diligence: analyzing hundreds of Word and PDF documents, extracting key provisions, and producing an Excel matrix with citations back to source pages. The question is: Should this skill contain all the reading, extraction, and generation logic, or delegate to specialized skills for separate concerns?
Dependency-Based Skills
A dependency-based skill contains only its unique logic. Word processing goes to the docx skill, PDF reading to the pdf skill, Excel generation to xlsx. Our tabular-review skill would orchestrate these different skills while integrating its own specialized logic.
The appeal is efficiency. Logic exists in one place. Fix a bug in the xlsx skill, and every skill that uses it benefits. The ecosystem remains maintainable as it grows.
The cost is fragility. Your skill depends on external code you don't control. A file processing skill updates: maybe it improves, maybe it introduces a regression that breaks your specific use case. You tested against v1.0, but your user has v1.1. Different behavior, same skill. The skill ecosystem currently has no mechanism to manage this. How do you declare dependencies? How do you pin versions? How do agents automatically install them? And dependency management doesn't get simpler as ecosystems grow. More skills means more edges in the dependency graph, more version conflicts, more coordination across authors, more potential for cascading breakage.
Token efficiency suffers too. A dependency-based skill loads the entire utility skill when invoked. If xlsx comprehensively covers formatting, charts, formulas, pivot tables, and conditional formatting, but your workflow only fills cells, you've loaded far more context than necessary.
While separation of concerns intuitively feels like the right path, the challenges above suggest it's not that simple.
Self-Contained Skills
A self-contained skill bundles everything it needs. PDF reading, Word parsing, and Excel generation would all live inside the tabular-review skill itself.
The appeal is stability. If the skill works today, it works tomorrow. Nothing external can break it. No upstream changes, no version conflicts, no missing dependencies.
Distribution is simpler too. Copy the folder, and it works. No need to tell the agent which skills to fetch, from which marketplace, which version. No handling of what happens when a dependency can't be downloaded. No wondering if the user has an incompatible version already installed. Self-contained skills sidestep the entire dependency management problem.
The cost is duplication. Ten skills that generate Excel files contain ten copies of Excel generation logic. Bug fixes don't propagate, nor do improvements.
Hence, neither approach is obviously correct. The skill ecosystem is young. The right choice will likely depend on the size of the ecosystem, how actively skills are maintained, and how much coordination exists between authors.