How to Handle Inter-Skill Dependencies When Installing Skills Selectively in Stitch Skills

Stitch Skills resolves inter-skill dependencies automatically by parsing SKILL.md manifests to build a directed acyclic graph (DAG), ensuring transitive dependencies are installed before the requested skill executes.

Stitch Skills is a plugin architecture in the google-labs-code/stitch-skills repository that enables developers to compose reusable units of functionality called "skills." When users install a single skill selectively, the platform must resolve its entire dependency chain to ensure proper execution. This article explains how the system uses manifest files and graph algorithms to handle these dependencies safely.

How Dependencies Are Declared in SKILL.md Manifests

Each skill folder contains a SKILL.md file that documents inputs, outputs, and dependencies. In plugins/stitch-build/skills/shadcn-ui/SKILL.md, the manifest lists required skills under a dependencies section.

The format distinguishes between required and optional dependencies. Required dependencies are installed automatically, while optional dependencies listed under optional_dependencies are only pulled in when explicitly requested. This declarative model allows the installer to build a complete dependency graph before executing any installation scripts.

The Resolution Algorithm: Building a Directed Acyclic Graph

When a user requests a specific skill, the installer constructs a DAG to represent the dependency relationships and prevent circular references.

The resolution process follows these steps:

1. The installer reads the target skill's SKILL.md and extracts its dependencies array.
2. It calls get_component_metadata(skill_name) from the stitch-utilities plugin to discover transitive dependencies recursively.
3. For each dependency found, the process repeats until the complete graph is built.
4. The DAG is topologically sorted to ensure dependencies are installed before dependent skills.
5. Installation scripts located in each skill's scripts/ folder execute in dependency order.

Circular dependencies are detected early during graph construction and reported as errors before any installation begins, preventing infinite loops.

Using get_component_metadata for Dependency Discovery

The stitch-utilities plugin exposes a helper function get_component_metadata that returns JSON metadata for any skill. This utility is documented in plugins/stitch-utilities/skills/stitch-loop/SKILL.md and enables selective installers to query dependency lists programmatically without manually parsing markdown files.

The returned payload includes structured version constraints, allowing the installer to validate compatibility against the local skill registry before proceeding.

Handling Edge Cases in Selective Installation

Version Conflicts: When two skills require different major versions of the same dependency, the installer aborts and suggests compatible alternatives rather than risking runtime errors.

Partial Installations: If a dependency is already present but out-of-date, the installer upgrades it before proceeding with dependent skills, ensuring the entire chain meets version constraints defined in each manifest.

Optional Dependencies: Skills can declare optional_dependencies in their SKILL.md. The installer skips these unless the user explicitly includes them in the installation request.

Practical Examples: Installing Skills with Automatic Dependency Resolution

The following examples demonstrate how the SDK and CLI automatically resolve the dependency chain when installing the shadcn-ui skill, which depends on react-components and react-native.

# Example: Python client using the Stitch SDK

from stitch_sdk import StitchClient

client = StitchClient()

# Request the "shadcn-ui" skill; dependencies are resolved automatically

client.install_skill("shadcn-ui")

# Example: CLI command (reading SKILL.md manifests)

stitch install shadcn-ui

# Output (simplified):

# → Resolving dependencies...

#   • react-components (required)

#   • react-native (required)

# Installing react-components...

# Installing react-native...

# Installing shadcn-ui...

# ✔ All skills installed successfully.

// Example payload returned by get_component_metadata for "shadcn-ui"
{
  "name": "shadcn-ui",
  "version": "1.2.0",
  "dependencies": [
    {"name": "react-components", "version": "^2.0"},
    {"name": "react-native", "version": "^3.1"}
  ],
  "optional_dependencies": []
}

Summary

• Declarative manifests: Each skill declares dependencies in SKILL.md files located in paths like plugins/stitch-build/skills/shadcn-ui/SKILL.md.
• Graph-based resolution: The installer builds a DAG from dependencies arrays and topologically sorts them to determine installation order.
• Discovery utility: The get_component_metadata function from stitch-utilities enables programmatic inspection of skill metadata.
• Safety mechanisms: The system detects circular dependencies, handles version conflicts by aborting with suggestions, and upgrades outdated dependencies automatically.
• Flexible installation: Supports both required and optional dependencies, allowing selective installation without breaking functionality.

Frequently Asked Questions

How does Stitch Skills detect circular dependencies during installation?

The installer builds a directed acyclic graph (DAG) from the dependencies listed in each skill's SKILL.md manifest. If the graph construction detects a cycle—where skill A depends on B, which depends on C, which depends on A—the installer aborts immediately and reports the error before executing any installation scripts.

What happens when two skills require different versions of the same dependency?

If two skills in the dependency chain require incompatible major versions of the same dependency, the installer aborts the process. It then suggests a compatible version or alternative skill that satisfies both constraints, preventing runtime conflicts that could break the Stitch platform.

Can I install a skill without its optional dependencies?

Yes. Skills declare optional dependencies under the optional_dependencies key in their SKILL.md files. By default, the installer only pulls in required dependencies listed under dependencies. Optional dependencies are only installed if you explicitly request them during the installation command or SDK call.

Where does the installer find the scripts to execute during skill installation?

Each skill folder contains a scripts/ directory with installation scripts specific to that skill. After resolving the dependency graph and sorting it topologically, the installer executes these scripts in order, ensuring all dependencies are satisfied before running the target skill's own installation script.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}