How Skills Work Together and Hand Off Tasks in the emilkowalski/skills Repository

Skills in the emilkowalski/skills repository collaborate through explicit hand-off cues written directly into markdown instruction files, parsed by the skills.sh CLI to route tasks between specialized agents.

This open-source framework treats each animation, review, or improvement task as a pipeline of discrete single-responsibility skills that invoke one another by name when their expertise boundaries are reached. The system is designed for deterministic, auditable workflows where no skill oversteps its scope.

The Anatomy of a Skill

Every skill in this repository follows a strict structural contract defined in its frontmatter and body:

---
name: <skill-name>
description: <what the skill does>
---

The markdown body then defines hard rules, execution sequences, and hand-off triggers. Skills remain self-contained—the animate skill in skills/animate/SKILL.md builds animations but explicitly stops when it needs a component rather than raw code.

Core Hand-Off Patterns

Skills collaborate through five primary patterns, each expressed as explicit instructions in the source markdown.

Component Selection Hand-Offs

When animate encounters a UI component requirement, it delegates rather than improvises.

In skills/animate/SKILL.md line 73:

### 3. Pick the tool — cheapest that works

| Need | Tool |
| --- | --- |
| … | **CSS transition** |
| … | **Motion** (`motion.dev`) |
| **Component needed** | **stop and invoke `pick-ui-library`** |

The pick-ui-library skill (skills/pick-ui-library/SKILL.md) returns library choice and usage snippets, then control returns to animate to complete steps 4-7.

Audit-Plan-Execute Pipelines

The improve-animations skill implements a four-phase workflow with internal and external hand-offs:

Phase	Sub-agent	Output
Recon	Internal	File discovery via grep
Audit	Parallel: audit-performance, audit-accessibility	Findings list
Vet	Internal	Prioritized, confirmed issues
Plan → Execute	improve-animations execute <plan>	Applied fixes

From skills/improve-animations/SKILL.md line 78:

"stop and wait for the user to select which findings become plans"

And line 96 for execution hand-off:

improve-animations execute <plan>

This pattern explicitly delegates to cheaper models when execution is straightforward: line 8 states plans should be "handed to any agent, including cheaper models."

Standards-Driven Lookups

Skills reference canonical values rather than hardcoding. The review-animations skill loads STANDARDS.md dynamically:

From skills/review-animations/SKILL.md line 17:

"load it whenever a finding needs a precise value or citation"

| Element | Duration |
| --- | --- |
| Dropdown | **150–250ms** (see [STANDARDS.md]#duration) |

Prototype-to-Implementation Chains

The prototype skill (skills/prototype/SKILL.md) generates multiple UI variants by calling concrete skills repeatedly:

"build multiple different versions of a UI piece you describe and go through them using a switcher"

Each variant invocation triggers animate, pick-ui-library, or other implementation skills as needed.

Typed Command Variants

Every skill declares supported invocation forms preventing accidental recursion:

• bare — default behavior
• quick / deep — depth variants
• plan <desc> — generate plan without executing
• execute <plan> — run existing plan

The CLI enforces these variants at parse time.

End-to-End Workflow: Animating a Toast Notification

This trace demonstrates how skills work together through explicit hand-offs:

1. User request: "animate a toast notification"
2. CLI routing: skills.sh matches to animate skill
3. Build sequence (skills/animate/SKILL.md lines 31-70):
   • Step 3 detects component need → stop and invoke pick-ui-library
4. pick-ui-library executes, returns sonner import and usage
5. Control returns to animate with component context
6. Completion: Steps 4-7 emit final implementation and summary (lines 88-94)

Reliability Mechanisms

The hand-off system depends on four architectural guarantees:

Explicit Metadata The name and description frontmatter fields make every skill discoverable programmatically.

Hard Rules Contract-enforcing sections prevent scope violations. From skills/improve-animations/SKILL.md line 22:

"Never modify source code"

Self-Contained Plans Line 24 mandates: "Plans must be fully self-contained" — file paths, exact tokens, and code excerpts embedded so executors need no hidden context.

Shared Reference Files STANDARDS.md, AUDIT.md, and PLAN-TEMPLATE.md live outside individual skills and are cited by reference, ensuring all agents read identical canonical values.

Key Source Files

Path	Responsibility	Hand-Off Role
skills/animate/SKILL.md	Build animations	Delegates to pick-ui-library for components
skills/pick-ui-library/SKILL.md	Select UI libraries	Returns implementation snippets to caller
skills/improve-animations/SKILL.md	Full codebase audit	Dispatches execution to execute <plan> variant
skills/review-animations/SKILL.md	Single diff review	Loads STANDARDS.md for precise values
skills/review-animations/STANDARDS.md	Canonical animation specs	Referenced by multiple skills
skills/prototype/SKILL.md	Generate UI variants	Invokes concrete skills per variant

Summary

• Skills hand off tasks through explicit markdown cues parsed by skills.sh
• animate → pick-ui-library is the canonical component delegation pattern
• improve-animations implements Recon → Audit → Vet → Plan → Execute with optional downgrading to cheaper models
• Hard rules and self-contained outputs prevent hidden dependencies between agents
• Shared standards files (STANDARDS.md) ensure consistent values across all skills
• Typed command variants (plan, execute, quick, deep) prevent accidental recursion

Frequently Asked Questions

How does the CLI know when to switch skills?

The skills.sh parser scans markdown for explicit invocation cues like "stop and invoke pick-ui-library" or "dispatch improve-animations execute <plan>". These are plain text instructions, not function calls—the runtime interprets them as routing commands.

Can skills call themselves recursively?

No—each skill declares typed variants in its documentation (e.g., bare, plan <desc>, execute <plan>). The CLI enforces these boundaries. A skill requesting execute cannot accidentally trigger itself; it must hand to a different capability or model tier.

What prevents a skill from modifying code it shouldn't?

Hard rules sections in each SKILL.md file. For example, improve-animations carries the explicit constraint "Never modify source code" (line 22). Plans are written to files; separate execution agents apply them, creating audit separation between planning and doing.

How do skills maintain consistent animation values?

Through shared reference files. Rather than hardcoding durations or easing curves, skills cite STANDARDS.md—a central document with canonical tables. When review-animations needs an exact value, it loads this file dynamically (line 17), ensuring all skills reference identical specifications.

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