proposal-agentskills-chaining

Proposal: Skill Chaining for Agent Skills

Problem

Agent Skills spec relies on "agent decides which skills to load" - no explicit ordering.

Current behavior:

• Skills are independent
• Agent decides order (implicit, unpredictable)
• No guarantee skills run in any particular sequence
• Works sometimes, fails mysteriously

Why this matters:

• Test chains need unit → integration → e2e order
• Security: scan → review → audit order
• Deploy: test → build → deploy order
• Current spec: "agent decides" is unpredictable
• Without explicit order: failures are mysterious
• Can't debug: don't know which skill ran when

Solution

Add chain field to skill metadata:

---
name: chain-test
description: Complete test chain...
metadata:
  chain:
    - test-smoke
    - test-unit
    - test-contract
    - test-e2e
---

### Fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `chain` | array | Yes | - | Ordered list of skill names to load |
| `async` | boolean | No | `false` | Sequential (false) or parallel (true) |
| `continue_on_error` | boolean | No | `true` | Continue if skill fails |
| `timeout` | integer | No | 0 | Max time per skill (0=unlimited) |
| `max_depth` | integer | No | 10 | Max nesting depth for nested chains |
| `parallel_limit` | integer | No | 5 | Max parallel skills when async=true |
| `validate_on_load` | boolean | No | `true` | Verify referenced skills exist |
| `cleanup_after` | boolean | No | `false` | Reset state after chain completes |

### Execution Fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `early_exit_on` | string | No | `none` | Exit on: `none` `failure` `success` `critical` |
| `continue_on_success` | boolean | No | `false` | Continue only if previous skill passed |
| `pass_state` | boolean | No | `true` | Pass outputs to next skill in chain |
| `retry_count` | integer | No | 1 | Run entire chain N times |
| `retry_until` | string | No | `none` | Repeat until: `none` `stable` `success` |
| `race_mode` | boolean | No | `false` | First skill to complete wins (parallel only) |

### Subfolder Restriction

All skills in `chain` must be same parent or lower (no escape up):
- ✅ `test/chain/SKILL.md` → `test/unit/SKILL.md` (same parent)
- ✅ `test/chain/SKILL.md` → `test/e2e/smoke/SKILL.md` (lower/deeper)
- ❌ `test/chain/SKILL.md` → `../audit/SKILL.md` (escape to parent)
- ❌ `/absolute/path` (not allowed)

This enforces hierarchy: chain at level N can only call skills at level N or deeper.

### Path Resolution

When chain references a skill by name:
1. Look in same subfolder first
2. Then look in subfolders at same level or deeper
3. Fail if skill not found (if validate_on_load: true)

### Output Format

Each skill in chain should return standard output:

```yaml
output: status: success | failure | critical result: "...description..." errors: [] metrics: {}

• status: outcome for chain decision
• result: human-readable summary
• errors: array of issues found
• metrics: timing, counts, etc.

State Passing

When pass_state: true, chain passes to next skill:

chain_state: previous_outputs: [] accumulated_errors: [] total_metrics: {}

• Previous skills' outputs available to next skill
• Errors accumulate across chain
• Metrics merge (sum/count)

Chain Calls Chain

Chains can call other chains (with max_depth limit):

• ✅ chain: [chain-test, chain-security]
• With depth limit to prevent infinite recursion

Async Flag Explanation

Default is sequential (false) because:

1. Most workflows need order (test before deploy)
2. Less surprising behavior
3. Explicit beats implicit
4. Can opt-in to parallel if needed