Handoff

Skill Handoff Protocol (auto-guidance)

This skill is loaded automatically. It defines how skills produce structured outputs, how downstream skills discover and consume them, and how artifacts are cleaned up after successful implementation.

---

1. Producing a Handoff Manifest

Every skill that generates output MUST write a handoff manifest as its final step.

1.1 Manifest Location and Naming

claudedocs/handoff---.yaml

Examples:

claudedocs/handoff-prd-payment-links-20260327T140000.yaml
claudedocs/handoff-ui-design-money-request-20260327T143000.yaml
claudedocs/handoff-spec-to-impl-payment-links-20260327T160000.yaml

1.2 How to Write

After producing your primary output(s), write the handoff manifest using the Write tool:

mkdir -p claudedocs
# Write the YAML using the schema in Section 2

This is not optional. Without a handoff manifest, downstream skills cannot discover your output and will ask redundant questions or miss context entirely.

---

2. Handoff Manifest Schema

schema_version: "2.0"
source_skill: ""
feature: ""
timestamp: ""

# ── Artifact Manifest ──────────────────────────────────────
# Every file or directory produced by this skill.
# Multi-artifact skills (ui-design, spec-to-impl) list ALL outputs.
artifacts:
  - path: ""
    type: ""
    status: "ready"            # ready | in-progress | failed
    summary: ""
    consumed_by:               # which downstream skills need this artifact
      - ""
    key_sections:              # sections that downstream skills should read
      - ""
    conditional: "" # omit if always produced

# ── Quality Gate ───────────────────────────────────────────
quality:
  status: "complete"           # complete | partial | has-ambiguities | blocked
  ambiguities: []              # list of unresolved questions
  blockers: []                 # list of issues preventing downstream consumption

# ── Downstream Suggestions ─────────────────────────────────
# Which skills should run next and what context they need.
suggested_next:
  - skill: ""
    reason: ""
    context: ""
    reads:                     # which artifacts from this manifest it needs
      - ""

# ── Upstream References ─────────────────────────────────────
# Which handoff manifests this skill consumed (forms a DAG).
consumed_from:
  - ""

# ── Lifecycle ───────────────────────────────────────────────
lifecycle:
  archivable_after:            # skills that must consume before archiving
    - ""
  archive_policy: "after-finalize"  # after-finalize | after-all-consumed | manual

# ── Tool-Specific Extensions ───────────────────────────────
# Optional blocks for design tools, CI systems, etc.
# stitch: { ... }             # Stitch MCP references (ui-design)
# figma: { ... }              # Figma MCP references (figma:figma-implement-design, figma:figma-generate-design)

2.1 Artifact Status Values

| Status | Meaning | Downstream behavior | |---|---|---| | ready | Artifact is complete and consumable | Read and use immediately | | in-progress | Skill is still producing this artifact | Wait or skip — check back later | | failed | Artifact generation failed | Do not consume; surface to user |

2.2 Quality Status Values

| Status | Meaning | Downstream behavior | |---|---|---| | complete | All artifacts ready, no open questions | Proceed normally | | partial | Some artifacts ready, others in-progress | Consume ready artifacts, wait on others | | has-ambiguities | Artifacts produced but with unresolved questions | Consume but flag ambiguities to user | | blocked | Cannot proceed until user resolves an issue | Do not consume; surface blockers |

2.3 Figma Extension Block

Skills that produce or consume Figma designs include a figma: extension block:

figma:
  file_key: ""
  file_url: ""
  pages:
    - page_name: ""
      screens:
        - screen_name: ""
          node_id: ""
          viewport: ""
          route_suggestion: ""
          screenshot_path: ""
  component_map:
    - component_name: ""
      component_key: ""
      node_ids: [""]
      variant_used: ""
  variable_bindings:
    - token_name: ""
      variable_key: ""
      value: ""
  generation_method: ""

Downstream skills use this block to:

• spec-to-impl FE agent: call get_design_context(fileKey, nodeId) for each screen
• figma:figma-implement-design: call get_design_context for individual components by component_key
• Both: map variable_bindings to CSS custom properties / Tailwind theme tokens

---

3. Consuming Handoff Manifests

On activation, every skill MUST run this discovery protocol:

3.1 Discovery — Find Relevant Upstream Manifests

# Step 1: List all handoff manifests, most recent first
ls -t claudedocs/handoff-*.yaml 2>/dev/null | head -10

# Step 2: For each manifest, check if this skill is in suggested_next[].skill
# Step 3: For each match, check quality.status != "blocked"
# Step 4: For each match, read the artifacts where status == "ready"

3.2 Consumption Protocol

1. Discover — Find manifests where suggested_next[].skill matches this skill's name
2. Filter — Skip manifests where quality.status == "blocked"
3. Read artifacts — For each suggested_next entry, read the files listed in reads[]
4. Use context — Apply the context field to understand what the upstream skill recommends
5. Skip questions — Do not ask the user for information that upstream artifacts already provide
6. Record — Add the consumed manifest path to your own consumed_from[] when you write your handoff

3.3 Handling Partial Handoffs

When an upstream manifest has quality.status == "partial":

• Consume artifacts with status: "ready" — proceed with what's available
• Skip artifacts with status: "in-progress" — do not block on them
• Report to the user: "Upstream has artifacts in progress. Proceeding with ready artifacts."
• If a critical artifact is in-progress (e.g., the schema design when you're the BE agent), wait and re-check after a delay

3.4 Graceful Degradation

Skills MUST work without handoff manifests. If no relevant manifests are found:

• Ask the user for the information that upstream artifacts would have provided
• Proceed normally — the skill is self-contained, just less informed

---

4. Multi-Artifact Skills

Skills that produce multiple files (ui-design, spec-to-impl, figma:figma-implement-design) use the same schema — they just have more entries in artifacts[].

4.1 Example: ui-design Handoff

schema_version: "2.0"
source_skill: "ui-design"
feature: "money-request"
timestamp: "2026-03-27T14:30:00Z"

artifacts:
  - path: "design/ux/ux-inventory.md"
    type: "ui-design"
    status: "ready"
    summary: "Screen inventory with fields, states, and user flows"
    consumed_by: ["spec-to-impl"]
  - path: "design/components/component-tree.md"
    type: "ui-design"
    status: "ready"
    summary: "Component hierarchy with props, states, and interactions"
    consumed_by: ["spec-to-impl"]
  - path: "design/components/testid-registry.md"
    type: "testid-registry"
    status: "ready"
    summary: "44 data-testid selectors for Playwright"
    consumed_by: ["verify-impl", "spec-to-impl"]
  - path: "design/visual-spec/tokens.md"
    type: "design-tokens"
    status: "ready"
    summary: "Color, spacing, typography, radius tokens"
    consumed_by: ["spec-to-impl"]
  - path: "design/a11y/a11y-spec.md"
    type: "ui-design"
    status: "ready"
    summary: "WCAG AA compliance spec with 3 issues to resolve"
    consumed_by: ["spec-to-impl", "ux-review"]
  - path: "design/DESIGN.md"
    type: "design-md"
    status: "ready"
    summary: "Portable design system spec"
    consumed_by: ["spec-to-impl", "figma:figma-implement-design"]

quality:
  status: "complete"
  ambiguities: []

suggested_next:
  - skill: "spec-to-impl"
    reason: "Design artifacts ready for FE implementation"
    context: "6 components, 44 testIDs, 3 screens. Consume design/DESIGN.md for tokens and design/components/ for component specs."
    reads:
      - "design/DESIGN.md"
      - "design/components/component-tree.md"
      - "design/components/testid-registry.md"
      - "design/visual-spec/tokens.md"
  - skill: "verify-impl"
    reason: "testIDs ready for Playwright selectors"
    context: "testid-registry.md has 44 selectors"
    reads:
      - "design/components/testid-registry.md"

lifecycle:
  archivable_after: ["spec-to-impl", "verify-impl"]
  archive_policy: "after-finalize"

4.2 Example: spec-to-impl Handoff

schema_version: "2.0"
source_skill: "spec-to-impl"
feature: "money-request"
timestamp: "2026-03-27T16:00:00Z"

artifacts:
  - path: "src/main/java/com/app/moneyrequest/"
    type: "code"
    status: "ready"
    summary: "Backend service: controller, service, repository, DTOs"
    consumed_by: ["verify-impl", "code-review", "code-audit"]
  - path: "src/main/resources/db/migration/V001__money_request.sql"
    type: "code"
    status: "ready"
    summary: "Liquibase migration for money_request tables"
    consumed_by: ["verify-impl"]
  - path: "src/ui/pages/MoneyRequest/"
    type: "code"
    status: "ready"
    summary: "React components for money request flow"
    consumed_by: ["verify-impl", "code-review"]
  - path: "e2e/test-plan.yaml"
    type: "test-plan"
    status: "ready"
    summary: "12 test cases across API, DB, and UI layers"
    consumed_by: ["verify-impl"]
  - path: "docs/observability-contract.md"
    type: "architecture"
    status: "ready"
    summary: "Logging, metrics, and tracing requirements"
    consumed_by: ["monitoring-plan"]

quality:
  status: "complete"
  ambiguities: []

consumed_from:
  - "claudedocs/handoff-prd-money-request-20260327T120000.yaml"
  - "claudedocs/handoff-ui-design-money-request-20260327T143000.yaml"

suggested_next:
  - skill: "verify-impl"
    reason: "Implementation complete, ready for live verification"
    context: "e2e/test-plan.yaml has 12 TCs. All P0 FRs covered. Run all 3 layers."
    reads:
      - "e2e/test-plan.yaml"
  - skill: "finalize"
    reason: "After verification passes, commit and PR"
    context: "3 agent branches to merge: feature/be-task-002, feature/dba-task-003, feature/fe-task-004"
    reads: []

lifecycle:
  archivable_after: ["verify-impl", "finalize"]
  archive_policy: "after-finalize"

4.3 Example: figma:figma-generate-design Handoff

schema_version: "2.0"
source_skill: "figma:figma-generate-design"
feature: "payment-links"
timestamp: "2026-03-27T15:00:00Z"

artifacts:
  - path: "https://figma.com/design/abc123/payment-links"
    type: "figma-design"
    status: "ready"
    summary: "4 screens built in Figma with design tokens and components"
    consumed_by: ["spec-to-impl", "figma:figma-implement-design"]
    key_sections: ["screens", "components", "tokens"]

figma:
  file_key: "abc123"
  file_url: "https://figma.com/design/abc123/payment-links"
  pages:
    - page_name: "Screens"
      screens:
        - screen_name: "Dashboard"
          node_id: "123:456"
          viewport: "1440px"
          route_suggestion: "/dashboard"
          screenshot_path: "claudedocs/screenshots/dashboard.png"
        - screen_name: "Dashboard Mobile"
          node_id: "123:789"
          viewport: "375px"
          route_suggestion: "/dashboard"
          screenshot_path: "claudedocs/screenshots/dashboard-mobile.png"
        - screen_name: "Create Link"
          node_id: "124:100"
          viewport: "1440px"
          route_suggestion: "/links/new"
          screenshot_path: "claudedocs/screenshots/create-link.png"
        - screen_name: "Link Details"
          node_id: "124:200"
          viewport: "1440px"
          route_suggestion: "/links/:id"
          screenshot_path: "claudedocs/screenshots/link-details.png"
  component_map:
    - component_name: "PaymentCard"
      component_key: "comp:abc"
      node_ids: ["123:456", "124:200"]
      variant_used: "default"
    - component_name: "StatusBadge"
      component_key: "comp:def"
      node_ids: ["124:200"]
      variant_used: "active"
  variable_bindings:
    - token_name: "--color-brand-primary"
      variable_key: "var:abc123"
      value: "#6366F1"
    - token_name: "--spacing-md"
      variable_key: "var:def456"
      value: "16px"
  generation_method: "combined"

quality:
  status: "complete"
  completeness_score: "100%"
  token_coverage: "22/24 tokens applied"
  component_coverage: "10/12 components instantiated"
  ambiguities: []
  gaps:
    - "Icon illustrations not available in Figma — used placeholder rectangles"

consumed_from:
  - "claudedocs/handoff-prd-payment-links-20260327T120000.yaml"
  - "claudedocs/handoff-ui-design-payment-links-20260327T143000.yaml"

suggested_next:
  - skill: "spec-to-impl"
    reason: "Figma designs ready for FE implementation"
    context: "File key abc123, 4 screens with node IDs. Use get_design_context for each screen. Design tokens applied as Figma variables."
    reads: []
  - skill: "figma:figma-implement-design"
    reason: "Individual components can be converted to code"
    context: "Component map has 10 components with Figma node IDs"
    reads: []

lifecycle:
  archivable_after: ["spec-to-impl", "figma:figma-implement-design"]
  archive_policy: "after-finalize"

---

5. Artifact Lifecycle and Cleanup

5.1 Lifecycle Stages

PRODUCED → CONSUMED → ARCHIVED
   ↑           ↑          ↑
   Skill    Downstream   /finalize
   writes   skills read  archives

5.2 What Gets Cleaned Up

| Artifact Type | Location | Cleanup Strategy | |---|---|---| | Handoff manifests | claudedocs/handoff-*.yaml | Never delete — audit trail | | Primary outputs | claudedocs/-*.md | Archive after /finalize completes | | Design artifacts | design/ | Archive after /finalize completes | | Test plans | e2e/test-plan.yaml | Keep — needed for regression testing | | Test evidence | e2e/reports/, screenshots | Keep — needed for evidence review | | Worktree branches | .worktrees/ | Delete after merge (handled by spec-to-impl) |

5.3 Archive Protocol

The /finalize skill runs this after a successful commit + PR:

# 1. Create archive directory
ARCHIVE="claudedocs/.archive/$(date +%Y%m%d-%H%M%S)-"
mkdir -p "$ARCHIVE"

# 2. Move primary outputs (NOT handoff manifests)
mv claudedocs/-*.md "$ARCHIVE/" 2>/dev/null

# 3. Move design artifacts if present
[ -d design/ ] && mv design/ "$ARCHIVE/design/" 2>/dev/null

# 4. Report
echo "Archived to: $ARCHIVE"
echo "Handoff manifests preserved in claudedocs/ (audit trail)"
echo "Test artifacts preserved in e2e/ (regression)"

5.4 Safety Rules

1. Never delete handoff manifests — they form the audit trail for the skill chain
2. Never auto-delete — always archive (move), never rm
3. Archive only after finalize — not after individual skill completion
4. Preserve test artifacts — e2e/test-plan.yaml, screenshots, and reports stay for regression
5. Ask before archiving design/ — design artifacts may be referenced by ongoing implementation
6. Add claudedocs/.archive/ to .gitignore — archived artifacts are local working state

5.5 Reference Tracking

A handoff manifest's lifecycle.archivable_after field lists which skills must consume the artifacts before they can be archived. The /finalize skill checks this:

# Before archiving, verify all consumers have consumed
for manifest in handoff_manifests:
    required = manifest.lifecycle.archivable_after
    consumed_by_skills = [m.source_skill for m in all_manifests
                          if manifest.path in m.consumed_from]
    if not all(s in consumed_by_skills for s in required):
        print(f"⚠️ {manifest.path} not yet consumed by: {missing}")
        # Do not archive — still needed

---

6. Skill Chain Examples

/prd → writes handoff-prd-payment-lin

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [OmexIT](https://github.com/OmexIT)
- **Source:** [OmexIT/claude-skills-pack](https://github.com/OmexIT/claude-skills-pack)
- **License:** MIT

Install and usage instructions live in the source repository linked above.