agent-runlog

SKILL.md

---
name: agent-runlog
description: Wrap shell commands with the agent-runlog CLI to capture concise, redacted run logs for debugging, CI reproduction, long-running agent commands, repeated failures, test/lint/build evidence, and handoffs where stdout/stderr plus git state should be preserved without flooding chat.
---

# Agent Runlog Skill

Use `agent-runlog` when command output needs to be preserved and summarized for debugging or handoff. It writes a small local ledger under `.agent-runs/<timestamp>/`.

## Default workflow

From the project root:

```bash
npx agent-runlog -- npm test
npx agent-runlog -- npm run lint
npx agent-runlog -- npm run build
```

Then inspect:

```bash
cat .agent-runs/*/report.md | tail -n 120
```

For automation:

```bash
npx agent-runlog --json -- npm test > run.json
```

## When to use

- Long or flaky test/build/lint runs.
- Reproducing CI failures locally.
- Capturing evidence before handing work to another agent.
- Diagnosing repeated error loops or noisy logs.

## Safety

- Redaction is on by default. Avoid `--no-redact` unless the user explicitly needs raw local logs.
- Do not wrap destructive commands without user approval.
- If logs may include private data, keep `.agent-runs/` local and summarize instead of posting full logs.

## Useful commands

```bash
npx agent-runlog -- <command> [args...]
npx agent-runlog -o .agent-runs/lint -- npm run lint
npx agent-runlog --cwd ./subproject -- npm test
npx agent-runlog --quiet -- npm test
```

## Vaultline integration

When the output needs to survive local machine/session boundaries, upload the run report to Vaultline and share a durable link.

```bash
# Save report path (example uses latest run)
REPORT_PATH=$(ls -t .agent-runs/*/report.md | head -n 1)

# Upload report with Vaultline SDK helper script
node -e '
const fs = require("node:fs");
const { Vaultline } = require("@builtbyecho/vaultline-sdk");
const path = process.env.REPORT_PATH;
const content = fs.readFileSync(path, "utf8");
const vault = new Vaultline({ apiKey: process.env.VAULTLINE_API_KEY });
vault.files.upload({
  path: `agent-runs/${Date.now()}-report.md`,
  content,
  contentType: "text/markdown"
}).then(r => console.log("Vaultline fileId:", r.fileId));
'
```

Use Vaultline for artifacts you want to hand off to another agent or reviewer without relying on local paths.