long-running-agent

name	long-running-agent
description	This skill converts planning docs and specs into phase-based task structures and prompts for long-running Claude agents. Use when setting up a multi-session agent workflow or breaking down a spec into phases with verification checkpoints.

Long-Running Agent Setup

Convert specs and planning documents into phase-based task structures for autonomous multi-session execution.

When to Use This Skill

• User has a spec or planning doc to execute with a long-running agent
• User wants to break down a project into phases with verification checkpoints
• User wants to create a claude-prompt.md for autonomous task execution

Source of Truth

Before doing anything, fetch and read this blog post for the core patterns: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

This blog from Anthropic's engineering team defines the effective patterns. Apply them directly.

Core Workflow

1. Gather Inputs

Request from the user:

• Spec/Planning Doc: The document to convert (required)
• Project Name: Short identifier
• Output Location: Where to create files

2. Read the Blog

Fetch the Anthropic blog post above. The key patterns are:

• Phase-based work with verification checkpoints
• Explicit feature/task enumeration (granular, testable items)
• Task file as progress tracker
• Git checkpointing after each task
• Strong constraints (no test deletion, no skipping phases)

3. Decompose into Phases and Tasks

Break the spec into:

Phases (3-8 typically):

• Logical groupings of related work
• Each phase has verification steps to test completion
• Agent completes ALL tasks in a phase, then stops for user verification

Tasks (per phase):

• Granular, implementable units
• Each task has specific steps
• Uses passes: true/false to track completion

Example structure from a real project:

Phase 1: Project Foundation (3 tasks)
  - setup-001: Initialize project structure
  - setup-002: Create environment config
  - types-001: Define core interfaces
  Verification: "Run npx tsc --noEmit, confirm no errors"

Phase 2: Storage & Skills (5 tasks)
  - storage-001: Create storage interface
  - skill-001 to skill-004: Create skill files
  Verification: "Confirm skills load, storage works"

... etc

4. Generate claude-task.json

Create the task file using assets/task-template.json structure:

• phases array with verification steps
• tasks array with passes: false initially
• Tasks reference their parent phase

Output: {project-root}/claude-task.json

5. Generate claude-prompt.md

Use assets/claude-prompt-template.md as the base.

Key sections to customize:

• Project overview and goal
• Key files list (SPEC.md, claude-task.json, any API docs)
• Phases table showing all phases
• File structure target
• Technical decisions specific to the project

Output: {project-root}/claude-prompt.md

6. Keep the SPEC

The original spec should remain as SPEC.md for the agent to reference when it needs detailed requirements.

Output Structure

{project-root}/
├── claude-prompt.md      # Agent instructions
├── claude-task.json      # Phases and tasks
└── SPEC.md               # Original planning doc (kept for reference)

Starting the Agent

Instruct the user:

@claude-prompt.md

The agent will read claude-task.json, find the current phase, and work through tasks until phase completion.

Key Patterns (from the blog)

1. Phase boundaries = verification checkpoints - Agent stops, user verifies, then continues
2. Complete ALL tasks in phase - No stopping mid-phase
3. Git commit after each task - task-XXX: description
4. Never skip phases - Sequential progression
5. Task file is the source of truth - Agent reads and updates it

Reference Materials

• assets/claude-prompt-template.md - Template for claude-prompt.md
• assets/task-template.json - Template for claude-task.json structure