long-running-agent - SKILL.md Agent Skill

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)

Phase boundaries = verification checkpoints - Agent stops, user verifies, then continues
Complete ALL tasks in phase - No stopping mid-phase
Git commit after each task - task-XXX: description
Never skip phases - Sequential progression
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