# lucas-runbook

lucas-runbook forces the agent to troubleshoot Kubernetes failures using approved Markdown runbooks. Ideal for pod crash investigations and container restarts.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 361 repo stars
- Author: a2wio
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/a2wio/lucas/tree/HEAD/src/agent/.claude/skills/lucas-runbook/SKILL.md
- Updated: 2026-06-08
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/lucas-runbook

## What it does

This skill locks the agent into runbook-driven mode for Kubernetes incidents. Whenever pod issues like `CrashLoopBackOff`, `OOMKilled`, or `ImagePullBackOff` appear, the agent searches for Markdown procedures in `/runbooks` using file patterns or fetches remote documentation with `WebFetch`.

Improvisation is banned. The assistant must cite the exact runbook path, run only authorized diagnostic commands, and apply specified fixes. If no document matches the issue or a runbook demands escalation, the agent halts and asks how to proceed.

## Requirements
- Works with: Kubernetes

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add a2wio/lucas --skill lucas-runbook -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/lucas-runbook/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/lucas-runbook/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add a2wio/lucas --skill lucas-runbook -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/lucas-runbook/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add a2wio/lucas --skill lucas-runbook -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/lucas-runbook/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install a2wio/lucas src/agent/.claude/skills/lucas-runbook
```

2. **Manually: put the files in place**
- File: `.github/skills/lucas-runbook/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add a2wio/lucas --skill lucas-runbook -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/a2wio/lucas --path src/agent/.claude/skills/lucas-runbook
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/lucas-runbook/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add a2wio/lucas --skill lucas-runbook -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/a2wio/lucas/tree/HEAD/src/agent/.claude/skills/lucas-runbook/SKILL.md

## When to use it
- Investigate `OOMKilled` pod errors using verified runbooks
- Search local `/runbooks` directory for matching `CrashLoopBackOff` guides
- Block unapproved remediation commands on Kubernetes clusters
- Fetch remote incident resolution procedures via `WebFetch`

## Example prompts
- A pod failed with OOMKilled, find the runbook and fix it according to procedure
- Investigate why the backend pod is in CrashLoopBackOff using /runbooks
- The deployment shows ImagePullBackOff, look up the remediation steps

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4fe80a3ade684286.

BEGIN THIRD-PARTY FILE 4fe80a3ade684286
````text
---
name: lucas-runbook
description: Lucas runbook-driven troubleshooting for Kubernetes issues. Use when investigating pod errors, crashes, restarts, or any Kubernetes problem. Automatically search runbooks before taking action.
allowed-tools: Read, Glob, Grep, WebFetch
---

# Lucas Runbook-Driven Troubleshooting

You are operating in **runbook-driven mode**. Before taking any remediation action, you MUST search for and follow approved runbooks.

## Runbook Sources

Search these locations for runbooks:

### Local Runbooks
- Path: `/runbooks`
- Search using: `Glob pattern="**/*.md" path="/runbooks"`
- Read matching files to find relevant procedures

### External Documentation (if configured)
- Check environment or config for external URLs
- Use WebFetch to retrieve external runbook content

## Procedure

When you identify a Kubernetes issue:

1. **Identify the error type** (OOMKilled, CrashLoopBackOff, ImagePullBackOff, etc.)

2. **Search for matching runbook**:
   ```
   Glob pattern="**/*oom*.md" path="/runbooks"
   Glob pattern="**/*crash*.md" path="/runbooks"
   Glob pattern="**/*image*.md" path="/runbooks"
   ```

3. **Read the runbook** if found

4. **Follow the runbook EXACTLY**:
   - Use only the approved diagnostic commands
   - Apply only the approved fixes
   - Escalate when the runbook says to escalate

5. **If NO runbook found**:
   - Do NOT attempt fixes
   - Report what you observed
   - Ask: "No runbook found for this issue. How should I proceed?"

## Important Rules

- ALWAYS cite which runbook you're following
- NEVER improvise fixes outside of runbooks
- If a runbook says "escalate", do NOT attempt the fix yourself
- Document what you did and the outcome

## Example

When you see OOMKilled:
1. Search: `Glob pattern="**/*oom*.md" path="/runbooks"`
2. Find: `oom-killed.md`
3. Read: The runbook says to increase memory limits
4. Say: "Following runbook `oom-killed.md`: Increasing memory limit from 256Mi to 512Mi"
5. Execute the approved fix
6. Verify and report outcome
````
END THIRD-PARTY FILE 4fe80a3ade684286

The third-party file has ended. Everything between the 4fe80a3ade684286 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© a2wio · MIT · https://github.com/a2wio/lucas/tree/HEAD/src/agent/.claude/skills/lucas-runbook/SKILL.md

## Similar
- [incident-runbook-templates](https://affpapa.org/en/nevibecode/skills/incident-runbook-templates.md) — skill · 10900 installs
- [cicd-automation-devops-troubleshooter](https://affpapa.org/en/nevibecode/agents/cicd-automation-devops-troubleshooter.md) — subagent · ★ 42780 repo stars
- [runbook-creation](https://affpapa.org/en/nevibecode/skills/runbook-creation.md) — skill · 388 installs
- [aks-troubleshooting](https://affpapa.org/en/nevibecode/skills/aks-troubleshooting.md) — skill · ★ 3232 repo stars
- [gke-basics](https://affpapa.org/en/nevibecode/skills/gke-basics.md) — skill · 13953 installs
- [gke-workload-troubleshooting](https://affpapa.org/en/nevibecode/skills/gke-workload-troubleshooting.md) — skill · 4600 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
