linear-agent-api

Files (1)

• SKILL.md

SKILL.md (first lines)

# Linear Agent API Skill

Comprehensive reference for Linear's Agent API, following the [Agent Interaction Guidelines (AIG)](https://linear.app/developers/aig).

## When to Use

- Verifying agent sessions are created correctly
- Checking activity streaming (thought, action, response)
- Implementing two-way communication (user input, stop signals)
- Debugging Linear integration issues

---

## Agent Session Lifecycle

Sessions track the lifecycle of an agent run:

| State | Meaning |
|-------|---------|
| `pending` | Session created, waiting for agent |
| `active` | Agent is working |
| `awaitingInput` | Agent needs user input |
| `error` | Something went wrong |
| `complete` | Work finished |

**Sessions are created automatically** when an agent is @mentioned or assigned as delegate.

---

## Agent Activity Types

| Type | Purpose | Who Creates |
|------|---------|-------------|
| `thought` | Agent reasoning, progress updates | Agent |
| `action` | Tool invocations (with optional `result`) | Agent |
| `elicitation` | Request user input or clarification | Agent |
| `response` | Final completion message | Agent |
| `error` | Report failure | Agent |
| `prompt` | User follow-up message | Human |

### Activity Payloads

```json
// thought - Agent thinking
{ 
  "content": { 
    "type": "thought", 
    "body": "Analyzing the codebase structure..." 
  } 
}

// action - Tool call
{ 
  "content": { 
    "type": "action", 
    "action": "edit_file", 
    "parameter": "src/main.rs" 
  } 
}

// action with result
{ 
  "content": { 
    "type": "action", 
    "action": "run_tests", 
    "result": "All 42 tests passed" 
  } 
}

// elicitation - Request input
{ 
  "content": { 
    "type": "elicitation", 
    "body": "Which database should I use?" 
  } 
}

// response - Completion
{ 
  "content": { 
    "type": "response", 
    "body": "Implementation complete. PR #123 created." 
  } 
}

// error - Failure
{ 
  "content": { 
    "type": "error", 
    "body": "Build failed: missing dependency" 
  } 
}
```

### Ephemeral Activities

Activities can be marked `ephemeral: true` for temporary status messages that get replaced by the next activity. Only `thought` and `action` types support this.

---

## Signals (Two-Way Communication)

### Human-to-Agent Signals

#### `stop` Signal

When user clicks "Send stop request" in Linear, agent receives a `prompt` activity with `signal: "stop"`.

**Agent MUST:**
1. **Halt immediately** - No further code changes or API calls
2. **Emit final activity** - `response` or `error` confirming stop
3. **Report current state** - What was completed, what remains

**CTO Implementation**: The `status-sync.rs` sidecar detects `signal: "stop"` in polled activities and triggers graceful shutdown via `/stop` endpoint.

### Agent-to-Human Signals

#### `auth` Signal

From 5DLabsInc/cto, AGPL-3.0.

More from 5DLabsInc/cto