renzrollon/shippable-skills / skills/productivity/session-retro
session-retro
VerifiedRetro the current session. Score it against session shapes, flag token waste with next-turn fixes, and propose wire-ins into the skills this conversation actually called.
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 90 B |
| CHANGELOG.md | markdown | 2.0 KB |
| README.md | markdown | 1.5 KB |
| SKILL.md | skill md | 22.1 KB |
| agents/openai.yaml | config | 171 B |
| evals/cases/current-session-report.yaml | config | 1.4 KB |
| evals/cases/focus-tokens.yaml | config | 1.7 KB |
| evals/cases/focus-wiring.yaml | config | 1.0 KB |
| evals/cases/refuse-transcript-reread.yaml | config | 1.4 KB |
| evals/eval.yaml | config | 826 B |
| references/session-shapes.md | markdown | 9.0 KB |
| references/skill-candidate-brief.md | markdown | 4.5 KB |
| references/tool-economy.md | markdown | 7.6 KB |
references/skill-candidate-brief.md
View on GitHub# Skill Candidate Brief: Author Contract
A durable handoff from a retro into a skill-author agent. It captures evidence
that a repeatable session procedure should become a new `SKILL.md`, without
writing the skill itself.
**Path:** `<handoff-dir>/skill-candidate-<slug>-<YYYYMMDD-HHMMSS>.md`
`<handoff-dir>` is a path the user passed or named in the request, else a `shippable-handoff-dir: <path>`
line in the instruction file (the first existing of `AGENTS.md`, `CLAUDE.md`,
`.github/copilot-instructions.md`; ignored when absolute or containing `..`), else the first existing of `.claude/handoff/`,
`.agents/handoff/`, `docs/handoff/`, else `.agents/handoff/` created. Slug = the proposed skill name in kebab-case.
**When to write**
- The retro finds a repeatable procedure not covered by an existing skill.
- Cap at the top 3 candidates per review. Skip one-offs, pure chat, and
duplicates of existing skills (suggest extending those instead).
**Bound the brief** (~1-3k tokens): cite the concrete moments and the tool
pattern; treat the procedure steps as hypotheses the author must refine.
---
## Template (stable: skill-author agents depend on these headings)
```markdown
# Skill Candidate Brief: <slug>
## Meta
- source: interactive | loop
- slug: <kebab-case proposed skill name>
- confidence: high | med | low
- created: <ISO-8601 timestamp>
- session_refs: <e.g. this session, 2026-08-21>
- evidence_basis: current-session (live context, no transcript re-read)
## Proposed Skill
- name: <kebab-case>
- description: <what it does AND when to use it>
- when_to_use: <bullet list of user phrases / contexts>
- when_not_to_use: <bullet list: overlaps, one-offs, better existing skills>
## Evidence
<!-- The concrete moments this session, the tool pattern, the assigned shape + score.
State clearly which steps below are inferred rather than directly observed. -->
## Procedure to Encode
<!-- Ordered steps a SKILL.md should teach. Hypotheses from what the session did: author must refine. -->
1. ...
2. ...
## Inputs / Outputs / Exit Criteria
- inputs: <args, flags, natural-language triggers>
- outputs: <files written, chat summary shape>
- exit_criteria:
- [ ] ...
## Related Existing Skills
<!-- From the enumerated skill list. Name overlaps and why this is NOT a duplicate
(or: "extend <skill> instead" and stop: do not invent a parallel skill). -->
## Open Questions
<!-- Gaps the author must resolve before writing SKILL.md (scope, tools, output path, etc.). -->
## Author Checklist
- [ ] Name + description are distinct from Related Existing Skills
- [ ] Trigger phrases are concrete enough to avoid under-triggering
- [ ] Procedure steps refined against at least one real session or user confirmation
- [ ] Inputs / outputs / exit criteria are testable
- [ ] Open questions resolved or explicitly deferred in the skill body
```
---
## Section rules
| Section | Rule |
|---------|------|
| **Meta.confidence** | `high` = a repeated procedural shape with durable domain knowledge; `med` = a single strong session; `low` = weak signal / thin evidence |
| **Evidence** | Cite the concrete moments. Never invent tool calls, quotes, or token counts. |
| **Procedure to Encode** | Hypotheses labeled as such. Prefer a locate → act → verify shape. |
| **Related Existing Skills** | Must check the enumerated skill list. Prefer "extend X" over a new skill when overlap is high. |
| **Author Checklist** | If unchecked blockers remain, say so when pointing the user at the brief. |
## Candidacy signals (what a retro looks for)
- The same multi-step procedure performed by hand that no skill covers
- A long, high-tool-count stretch reinventing a workflow absent from existing skills
- A mid/low shape score where a skill would have prevented the named failure mode
- A clear procedural shape (locate → transform → verify) with durable domain knowledge
**Skip:** one-off Targeted Fixes, chat-only stretches, and work already covered
by an existing skill (suggest extending that skill instead).
## Chat reply after write
Do **not** re-dump full briefs into chat. Reply with:
1. Paths to each `skill-candidate-*.md` written
2. A one-line summary per candidate (slug + confidence + why)
3. "Hand these to a skill-author agent to write the SKILL.md"
## Author consumption
A skill-author agent reads the brief, resolves the Open Questions with the
user, then writes `skills/<bucket>/<name>/SKILL.md` (and docs / manifest
wiring as needed). Prefer the brief's recommendations over re-deriving the
procedure; reopen the session only for gaps or contradictions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |