What is session-to-guideline?

A tool that turns a pi session transcript—a JSONL file containing one conversation's events—into a reusable Markdown guide for working with an AI.

Use it to document how a task was completed, summarize tool use and file changes, explain what needed steering, and create a repeatable checklist.

It preserves which prompts and steering choices worked, so similar tasks can be repeated with less trial and error.

session-to-guideline — Skill for Claude Code and Codex by BlackBeltTec

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent

npx skills add BlackBeltTechnology/pi-agent-dashboard --skill session-to-guideline

Clone the repo

git clone --depth 1 https://github.com/BlackBeltTechnology/pi-agent-dashboard

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/blackbelttechnology/pi-agent-dashboard/session-to-guideline/github.svg)](https://agentmods.dev/skills/blackbelttechnology/pi-agent-dashboard/session-to-guideline)

Your own site

<a href="https://agentmods.dev/skills/blackbelttechnology/pi-agent-dashboard/session-to-guideline"><img src="https://agentmods.dev/badge/skills/blackbelttechnology/pi-agent-dashboard/session-to-guideline/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/blackbelttechnology/pi-agent-dashboard/session-to-guideline"><img src="https://agentmods.dev/badge/skills/blackbelttechnology/pi-agent-dashboard/session-to-guideline.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 93 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 3,235 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe. Third-party audits

NVIDIA SkillSpector warn 7 Sept 2026

SkillSpector: 15 findings, up to high

These are SkillSpector’s own severities. On a checked sample its high-severity flags on skills were ~96% false positives — a documented command, a public API, a “never do X” rule — so we show them as a caution to read, not a verdict. Why →

high Anti-Refusal · line 123
Skill instructs the agent to omit warnings, disclaimers, or ethical commentary. Stripping safety caveats hides risk from the user and is a common jailbreak preamble.

Fix: Remove instructions that suppress warnings, disclaimers, or ethical commentary. Let the agent surface safety-relevant caveats to the user.
medium Rogue Agent · line 3
Skill establishes unauthorized persistence across sessions via cron jobs, startup scripts, or state files. Session persistence allows an attacker to maintain access beyond the current interaction.

Fix: Remove any persistence mechanisms (cron jobs, startup scripts, state files). Skills should not maintain state across sessions without explicit user consent.
medium MCP Rug Pull · line 17
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 40
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 41
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 42
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 56
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 149
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 186
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 187
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 188
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 189
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 190
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 191
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]
medium MCP Rug Pull · line 202
npx commands without a version suffix (e.g. @1.0.0) create a rug-pull risk if the upstream server is compromised and publishes a malicious update.

Fix: Pin the version: npx @scope/[email protected]

How audits are shown

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00093	$0.03235
Opus 5	$0.00046	$0.01618
Sonnet 5	$0.00019	$0.00647
Haiku 4.5	$0.00009	$0.00324

Measured 12d ago against content hash 0b921d81d959, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-11, from the pricing page.

Security

Grade A, and why

session-to-guideline scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 12d ago.

The scan reads SKILL.md. This mod also ships 2 executable files (scripts/extract_session.ts, scripts/list_sessions.ts), listed below but not scanned — reading those needs a real analyzer, not pattern matching.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

packages/authoring-toolkit/.pi/skills/session-to-guideline/SKILL.md · 206 lines

How it starts

The opening of the file, as written. The whole thing — 206 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Session → Collaboration Guideline

Produces a Markdown document that reads like a playbook for collaborating with the AI on a task — not a raw transcript. It separates the goal from the steering, surfaces the skills/memories created and why they work, and ends with a reproduce-it checklist.

Two layers:

Deterministic extract (scripts/extract_session.ts) — parses the session JSONL on the active branch and emits a structured facts sheet (prompts in order, tool usage, files written/edited, searches, skills/memories created, failed commands, cost). This is raw material, not the deliverable. TypeScript, run with npx tsx (repo convention).
Synthesis — read the facts sheet and write the guideline using references/guideline-template.md. The why it's effective and what to steer parts require judgment. Run it inline for a single session, or delegate to the SessionGuideline subagent for batch / past-session application (see below) — the synthesis is self-contained (facts sheet in, one guideline out), so it isolates cleanly.

Where sessions live

~/.pi/agent/sessions/--<cwd-with-slashes-as-dashes>--/<timestamp>_<uuid>.jsonl (JSONL tree; see the pi session-format docs). The scripts locate files for you.

Worktrees are included by default. A project's OpenSpec work runs in .worktrees/<name> sub-checkouts, which get their own encoded session dir (--<project>-.worktrees-<name>--). Both scripts resolve a --cwd to the project root + every .worktrees/* worktree, so project-scoped listing/latest covers worktree sessions too (rows tagged [wt:<name>]). Pass --no-worktrees for the old root-only behavior. Running from inside a worktree still lists the whole project (the root is recovered by stripping /.worktrees/<name>).

Procedure

Pick the session. If the user didn't name one, list candidates:
```
npx tsx scripts/list_sessions.ts --cwd "$(pwd)" --limit 20      # this project + its worktrees
npx tsx scripts/list_sessions.ts --cwd "$(pwd)" --no-worktrees  # project root only
npx tsx scripts/list_sessions.ts --all --limit 30               # every project
```
Worktree rows are tagged [wt:<name>] so you can tell root work from worktree work. (tsx runs the .ts directly, no build step.) Show the table and confirm which one (by 8-char id or # index). The current live session is usually #0/latest; documenting a finished prior session gives a complete picture (the live one won't include the not-yet-written tail).

Read the full file on GitHub · 206 lines

Files

What ships with it

3 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

12d ago First seen · 206 lines · 93 tokens per session scan A 0b921d81d959

Subscribe to this mod's changes

session-to-guideline is a skill published in the GitHub repository BlackBeltTechnology/pi-agent-dashboard (279 stars, last pushed yesterday), licensed MIT. It adds 93 tokens to every session and 3,235 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Building agents Writing and docs agent agent-framework agent-orchestration agent-skills agentic agentic-ai

session-to-guideline

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

Session → Collaboration Guideline

Where sessions live

Procedure

What ships with it

What this file has done since we first saw it

Other skills, from other repositories

goga-cookbook

goga-plan-by-design

goga-review-plan

goga-define-experience

goga-accept-manifest-review

goga-cells-by-brainstorm