# Merge pull request #10 from entireio/codex/session-to-skill-skill

`c0d4b11`→[main](/content/gh/entireio/skills/commits/main/index.html)·
  
blackgirlbytes·2mo ago·2 files·+228 added/-0 removed

Add session-to-skill orchestrator skill

## Changes

2

- MREADME.md+18
- skills/session-to-skill

- ASKILL.md+210

```
18 unmodified lines
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
146 unmodified lines

186
187
188
189
190
191
192
193
194

18 unmodified lines

- resolves checkpoints from: local `entire/checkpoints/v1` branch, `.entire/settings.json` `checkpoint_remote`, or nearby local clone
- filters sessions by agent name (e.g. "codex", "gemini") when mentioned

### `session-to-skill`

Turns Entire session history into a focused reusable skill draft without making the user manually find, paste, or reconstruct old agent conversations.

Current behavior:

- asks what reusable behavior the user wants to extract before reading transcripts
- accepts an explicit session ID or checkpoint ID when the user already has one
- searches Entire history with `entire search "<query>" --json` when the user describes a repeated workflow
- expands selected checkpoints with `entire explain --checkpoint <id> --full --no-pager`
- reads active session metadata from `.git/entire-sessions/<session-id>.json` when needed
- extracts durable lessons such as repo conventions, validation commands, user corrections, required inputs, and behaviors to avoid
- drafts a focused `SKILL.md` instead of recapping the whole session
- asks before writing, installing, or overwriting a skill

### `explain`

Traces source code back to the original conversation where it was created. Use `/explain` with a function, file, or line of code to understand _why_ it exists.
146 unmodified lines

- "hand off the codex session"
- "pick up where codex left off"
- "hand off checkpoint 7b7c2be8a262"
- "turn my blog publishing workflow into a skill"
- "make a skill from session 019ddbc1-a5bf-77e2-8b7a-b4094e850347"
- "I keep doing the same release notes workflow; find the sessions and draft a skill"
- `/explain parseConfig` — why does this function exist?
- `/explain src/auth.ts` — what drove this file's creation?
- "search past work for rate limiting"
```

MREADME.md+18

````
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

---
name: session-to-skill
description: Use when the user wants to turn one or more Entire-tracked sessions, checkpoints, or repeated agent workflows into a reusable agent skill.
---

# Session To Skill

Use this skill to help the user turn Entire session history into a focused skill draft.

The goal is not to convert a whole transcript mechanically. Treat sessions and checkpoints as source material, then extract the reusable workflow the user wants to repeat.

## Response Format

Begin the first response to this skill invocation with the line:

`Entire Session To Skill:`

followed by a blank line, then the content.

- Apply the header to the **first response of the invocation only.** Do not re-print it on follow-up turns within the same invocation.
- Do **not** include the header on error or early-exit responses, such as when Entire is not installed, the current directory is not a git repository, no relevant sessions are found, or the user has not identified what reusable behavior they want.

## Rules

1. First identify the reusable behavior the skill should capture. If the user has not said what the skill should help with, ask that question before reading transcripts.
2. Use Entire history as evidence. Prefer `entire search`, `entire session current`, session metadata files, and `entire explain` over asking the user to paste old transcripts.
3. A skill draft should be focused on future behavior, not a recap of the session. Preserve durable workflow, repo conventions, user corrections, commands, validation, and things to avoid.
4. When several sessions may be relevant, summarize the repeated workflow pattern, recommend a source set, and ask the user to confirm before expanding transcripts.
5. Do not write, install, or overwrite a skill file unless the user explicitly approves the destination. By default, present the `SKILL.md` draft in the response.
6. Do not include secrets, private credentials, raw logs, or unnecessary transcript detail in the generated skill.

## Workflow

### 1. Clarify The Skill Target

If the user gives a clear target, continue. Examples:

- "turn my blog publishing workflow into a skill"
- "make a skill from session 019..."
- "I keep doing release note drafting; make that reusable"

If the target is vague, ask:

```text
What should this skill help you do repeatedly?
```

If the user wants a specific skill name, use it. Otherwise infer a short hyphen-case name from the target, then confirm it before writing files.

### 2. Infer The Repeated Pattern

If the user gives a checkpoint ID, skip to checkpoint expansion.

If the user gives a session ID, read the matching session metadata from:

```text
.git/entire-sessions/<session-id>.json
```

If the user describes a repeated workflow but does not give a session or checkpoint, search Entire history with terms from the target:

```bash
entire search "<workflow terms>" --json
```

Use repo, branch, author, or date filters when the user provides them:

```bash
entire search "<workflow terms>" --json --repo owner/name --branch branch-name --author "Name" --date month
```

Interpret search results carefully:

- If `entire search` returns valid JSON with `"total": 0` or an empty `results` array, do **not** call it an authentication failure. Say no indexed matches were found, then fall back to local session metadata.
- Only say authentication is required if the command output explicitly says authentication, login, or credentials are required.
- If search fails for any other reason, report the short error and fall back to local session metadata when available.

When falling back locally, inspect `.git/entire-sessions/*.json` and match against `last_prompt`, `description`, `files_touched`, `started_at`, `last_interaction_time`, `agent_type`, and the user's workflow terms.

Review the top results and infer the repeated workflow pattern before showing raw session choices. Lead with the pattern, not the IDs.

Present:

- the repeated workflow you think the user wants to capture
- the strongest source set you recommend using
- what each source contributes in plain language, such as "core workflow", "image handling", "validation", or "copy-editing pattern"
- any sessions you plan to ignore because they look metadata-only, duplicate, or one-off

Keep session IDs and checkpoint IDs as supporting details, not the main decision surface. Ask the user to confirm the pattern and source set before expanding detailed transcripts.

Example:

```text
I found a repeated workflow: publishing blog posts in entire.io from drafts, using repo-specific front matter, slugged asset folders, user-provided images, and website checks.

I recommend using the strongest matching sessions as source material:
- core workflow: <session-id>
- image handling: <session-id>
- validation mechanics: <session-id>

I will ignore metadata-only or one-off edit sessions unless you want them included. Should I continue with this source set?
```

### 3. Read Source Material

For a checkpoint, run:

```bash
entire explain --checkpoint <checkpoint-id> --full --no-pager
```

If full output fails and the user wants more detail, fall back to:

```bash
entire explain --checkpoint <checkpoint-id> --raw-transcript --no-pager
```

For an active or current session, prefer:

```bash
entire session current
```

If the installed Entire CLI does not support the singular `session` group yet, use the session metadata fallback directly: inspect `.git/entire-sessions/*.json`, pick the relevant session by `last_interaction_time`, `started_at`, `agent_type`, or the user's requested agent, then extract `transcript_path`.

When reading a raw transcript, extract relevant conversation and tool-call lines without dumping them to the user:

```bash
grep -E '"type":"(message|function_call|user|assistant)"' <transcript_path> | cut -c1-2000
```

For large transcripts, inspect the first prompts and final state first:

```bash
grep -E '"type":"(message|function_call|user|assistant)"' <transcript_path> | head -40 | cut -c1-2000
grep -E '"type":"(message|function_call|user|assistant)"' <transcript_path> | tail -160 | cut -c1-2000
```

If the session metadata lists files touched, inspect only files needed to understand durable conventions. Avoid broad repo exploration unless the skill target requires it.

### 4. Extract Durable Lessons

Before drafting, privately identify:

- the repeated goal the future skill should accomplish
- triggers that should activate the skill
- required inputs the future agent should ask for
- repo-specific paths, file formats, front matter, naming, or asset placement
- commands and checks that proved the workflow worked
- user corrections and preferences from the session
- failed approaches or behaviors to avoid
- what was one-off and should not go into the skill

If multiple sessions were selected, combine only the repeated or clearly reusable lessons. Do not average contradictory instructions; ask the user to choose when sessions disagree.

### 5. Draft The Skill

Create a complete `SKILL.md` draft with required front matter:

```markdown
---
name: <hyphen-case-skill-name>
description: Use when <specific trigger and task>.
---
```

The body should include:

- a short purpose statement
- clear rules or guardrails
- a step-by-step workflow
- exact commands only when they are part of the reusable behavior
- expected outputs and validation steps
- failure handling or when to ask the user

Keep the skill concise. Do not include the session recap, full transcript excerpts, checkpoint IDs, or implementation notes unless they are essential to future use.

### 6. Deliver And Offer Installation

Present the `SKILL.md` draft first unless the user already gave an explicit write path.

After presenting the draft, ask whether the user wants it installed globally. Recommend the cross-agent path:

```text
~/.agents/skills/<skill-name>/SKILL.md
```

Use this install prompt shape:

```text
Do you want me to install this skill globally?

Recommended:
- Cross-agent: ~/.agents/skills/<skill-name>/SKILL.md

Other options:
- Codex only: ~/.codex/skills/<skill-name>/SKILL.md
- Write to a repo-local draft: skills/<skill-name>/SKILL.md
- Leave as draft only
```

Only write files after the user chooses a destination. If the destination already exists, ask before overwriting it.

Do not create symlinks unless the user explicitly asks for a development-linked install. If they ask for a symlink, explain the source and target paths before creating it.

After writing a skill file, summarize:

- where it was written
- which session(s) or checkpoint(s) informed it
- any assumptions or open questions
```