elliot-stack 1.0.25 → 1.0.28
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +4 -0
- package/package.json +1 -1
- package/skills/estack-active-learning-tutor/SKILL.md +1 -66
- package/skills/estack-better-title/SKILL.md +2 -96
- package/skills/estack-chris-voss/SKILL.md +1 -95
- package/skills/estack-claude-md-optimizer/SKILL.md +200 -0
- package/skills/estack-claude-md-optimizer/references/gary_tan_router_claude_md_mentality.md +247 -0
- package/skills/estack-claude-md-optimizer/references/theo_claude_md_mentality.md +113 -0
- package/skills/estack-claude-md-optimizer/routes/create.md +84 -0
- package/skills/estack-claude-md-optimizer/routes/refine.md +69 -0
- package/skills/estack-claude-md-optimizer/routes/scale-check.md +56 -0
- package/skills/estack-claude-md-optimizer/routes/session-capture.md +70 -0
- package/skills/estack-customer-discovery/SKILL.md +1 -95
- package/skills/estack-flight-planner/SKILL.md +2 -101
- package/skills/estack-flight-planner/scripts/fetch_flights.py +1 -1
- package/skills/estack-flight-planner/scripts/filter_flights.py +4 -4
- package/skills/estack-github-issue-tracker/SKILL.md +1 -84
- package/skills/estack-github-issue-tracker/bin/tracker-tools.cjs +1 -1
- package/skills/estack-prompt-builder-coach/SKILL.md +1 -2
- package/skills/estack-read-claude-session-history/SKILL.md +2 -3
- package/skills/estack-read-claude-session-history/references/recipes.md +1 -1
- package/skills/estack-repo-search/SKILL.md +1 -30
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Elliot Drel
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -20,8 +20,12 @@ This installs skills to `~/.agents/skills/` and symlinks them into `~/.claude/sk
|
|
|
20
20
|
| **Active Learning Tutor** | `/estack-active-learning-tutor` | Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking |
|
|
21
21
|
| **Better Title** | `/estack-better-title` | Renames Claude Code chat sessions with descriptive titles |
|
|
22
22
|
| **Chris Voss** | `/estack-chris-voss` | Applies negotiation principles from *Never Split the Difference* |
|
|
23
|
+
| **CLAUDE.md Optimizer** | `/estack-claude-md-optimizer` | Creates, refines, and maintains CLAUDE.md / AGENTS.md files as short hand-authored letters of intent |
|
|
23
24
|
| **Customer Discovery** | `/estack-customer-discovery` | Guides through customer discovery — validating ideas, outreach, interviews, and analysis |
|
|
25
|
+
| **Flight Planner** | `/estack-flight-planner` | Finds and ranks flights between two airports with config-driven preferences and optional ground-shuttle pairing |
|
|
24
26
|
| **GitHub Issue Tracker** | `/estack-github-issue-tracker` | Tracks and manages GitHub issues across repos |
|
|
27
|
+
| **Prompt Builder Coach** | `/estack-prompt-builder-coach` | Four-part kit for shaping, building, auditing, and scoping prompts for AI agents |
|
|
28
|
+
| **Read Claude Session History** | `/estack-read-claude-session-history` | Searches, reads, recovers, and compares Claude Code session history across sessions, projects, and backups |
|
|
25
29
|
| **Repo Search** | `/estack-repo-search` | Clones and searches external GitHub repos to answer questions about their code |
|
|
26
30
|
|
|
27
31
|
## Hooks
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: estack-active-learning-tutor
|
|
3
|
-
version: 1.0.
|
|
3
|
+
version: 1.0.2
|
|
4
4
|
description: (active-learning-tutor) Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking. Use when the student says they want to study, learn, prep for an exam, be quizzed on a chapter, work through a practice test together, or be taught a topic conceptually rather than lectured.
|
|
5
5
|
disable-model-invocation: true
|
|
6
6
|
---
|
|
@@ -339,71 +339,6 @@ When in doubt about the shape of a Teaching turn, read `references/teaching-turn
|
|
|
339
339
|
|
|
340
340
|
---
|
|
341
341
|
|
|
342
|
-
## Skill Feedback
|
|
343
|
-
---
|
|
344
|
-
|
|
345
|
-
## Skill Feedback
|
|
346
|
-
|
|
347
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
348
|
-
|
|
349
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
350
|
-
|
|
351
|
-
```bash
|
|
352
|
-
gh issue create \
|
|
353
|
-
--repo ElliotDrel/e-stack \
|
|
354
|
-
--title "estack-active-learning-tutor: <concise summary>" \
|
|
355
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
**If `gh` is not installed**, build a pre-filled URL:
|
|
359
|
-
|
|
360
|
-
```bash
|
|
361
|
-
python3 -c "
|
|
362
|
-
import urllib.parse
|
|
363
|
-
title = 'estack-active-learning-tutor: <concise summary>'
|
|
364
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
365
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
366
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
367
|
-
"
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
Share the printed URL with the user and offer to open it in their browser.
|
|
371
|
-
|
|
372
|
-
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|
|
373
|
-
|
|
374
|
-
---
|
|
375
|
-
|
|
376
|
-
## Skill Feedback
|
|
377
|
-
|
|
378
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
379
|
-
|
|
380
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
381
|
-
|
|
382
|
-
```bash
|
|
383
|
-
gh issue create \
|
|
384
|
-
--repo ElliotDrel/e-stack \
|
|
385
|
-
--title "estack-active-learning-tutor: <concise summary>" \
|
|
386
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
387
|
-
```
|
|
388
|
-
|
|
389
|
-
**If `gh` is not installed**, build a pre-filled URL:
|
|
390
|
-
|
|
391
|
-
```bash
|
|
392
|
-
python3 -c "
|
|
393
|
-
import urllib.parse
|
|
394
|
-
title = 'estack-active-learning-tutor: <concise summary>'
|
|
395
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
396
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
397
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
398
|
-
"
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
Share the printed URL with the user and offer to open it in their browser.
|
|
402
|
-
|
|
403
|
-
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
342
|
## Skill Feedback
|
|
408
343
|
|
|
409
344
|
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: estack-better-title
|
|
3
|
-
version: 1.0.
|
|
3
|
+
version: 1.0.3
|
|
4
4
|
description: (better-title) Suggest better chat session titles and rename the session
|
|
5
5
|
disable-model-invocation: true
|
|
6
6
|
allowed-tools: Bash, AskUserQuestion
|
|
@@ -30,7 +30,7 @@ Write the title from those answers, NOT from a chronological recap of the chat.
|
|
|
30
30
|
- **Title the outputs, not the journey** — exclude mistakes, dead ends, and abandoned approaches. They're not searchable and not useful context for future-you.
|
|
31
31
|
- **Use plain language a future-you would search for.** Avoid jargon like "passthrough," "edge cases," "toggle logic," "auto-cd," "refactored," "overhaul." Say what it does in normal words.
|
|
32
32
|
- **Weight by long-term reference value.** If something will stop mattering in weeks or months (temporary fixes, current-state notes, "until X is available" workarounds), mention it briefly but don't lead with it.
|
|
33
|
-
- List key outputs separated by dashes, commas, or similar (e.g. "Reverse-Engineering /rename, PR #33165 Comment, and Building /better-title Skill")
|
|
33
|
+
- List key outputs separated by dashes, commas, or similar (e.g. "Reverse-Engineering /rename, PR #33165 Comment, and Building /estack-better-title Skill")
|
|
34
34
|
- Cover 2-4 main outputs. Resist cramming everything in — first-pass attempts tend to over-include.
|
|
35
35
|
- Are detailed enough that someone skimming a session list can tell exactly what they'd find inside
|
|
36
36
|
- Typically 8-20 words — longer is fine if it adds useful detail
|
|
@@ -77,100 +77,6 @@ gh issue create \
|
|
|
77
77
|
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
78
78
|
```
|
|
79
79
|
|
|
80
|
-
**If `gh` is not installed**, build a pre-filled URL and share it so the user can click, review, and submit:
|
|
81
|
-
|
|
82
|
-
```bash
|
|
83
|
-
python3 -c "
|
|
84
|
-
import urllib.parse
|
|
85
|
-
title = 'estack-better-title: <concise summary>'
|
|
86
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
87
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
88
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
89
|
-
"
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Share the printed URL with the user. They click it, review the pre-filled title and body, then click **Submit new issue**.
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
## Skill Feedback
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## Skill Feedback
|
|
100
|
-
|
|
101
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
102
|
-
|
|
103
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
104
|
-
|
|
105
|
-
```bash
|
|
106
|
-
gh issue create \
|
|
107
|
-
--repo ElliotDrel/e-stack \
|
|
108
|
-
--title "estack-better-title: <concise summary>" \
|
|
109
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
**If `gh` is not installed**, build a pre-filled URL:
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
python3 -c "
|
|
116
|
-
import urllib.parse
|
|
117
|
-
title = 'estack-better-title: <concise summary>'
|
|
118
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
119
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
120
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
121
|
-
"
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Share the printed URL with the user and offer to open it in their browser.
|
|
125
|
-
|
|
126
|
-
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
## Skill Feedback
|
|
131
|
-
|
|
132
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
133
|
-
|
|
134
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
135
|
-
|
|
136
|
-
```bash
|
|
137
|
-
gh issue create \
|
|
138
|
-
--repo ElliotDrel/e-stack \
|
|
139
|
-
--title "estack-better-title: <concise summary>" \
|
|
140
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
**If `gh` is not installed**, build a pre-filled URL:
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
python3 -c "
|
|
147
|
-
import urllib.parse
|
|
148
|
-
title = 'estack-better-title: <concise summary>'
|
|
149
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
150
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
151
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
152
|
-
"
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Share the printed URL with the user and offer to open it in their browser.
|
|
156
|
-
|
|
157
|
-
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|
|
158
|
-
|
|
159
|
-
---
|
|
160
|
-
|
|
161
|
-
## Skill Feedback
|
|
162
|
-
|
|
163
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
164
|
-
|
|
165
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
gh issue create \
|
|
169
|
-
--repo ElliotDrel/e-stack \
|
|
170
|
-
--title "estack-better-title: <concise summary>" \
|
|
171
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
172
|
-
```
|
|
173
|
-
|
|
174
80
|
**If `gh` is not installed**, build a pre-filled URL:
|
|
175
81
|
|
|
176
82
|
```bash
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: estack-chris-voss
|
|
3
|
-
version: 1.0.
|
|
3
|
+
version: 1.0.2
|
|
4
4
|
description: >
|
|
5
5
|
(chris-voss) Applies Chris Voss negotiation principles from *Never Split the Difference* to any situation
|
|
6
6
|
where understanding human psychology, persuasion, or influence would improve the output. Use
|
|
@@ -93,100 +93,6 @@ gh issue create \
|
|
|
93
93
|
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
94
94
|
```
|
|
95
95
|
|
|
96
|
-
**If `gh` is not installed**, build a pre-filled URL and share it so the user can click, review, and submit:
|
|
97
|
-
|
|
98
|
-
```bash
|
|
99
|
-
python3 -c "
|
|
100
|
-
import urllib.parse
|
|
101
|
-
title = 'estack-chris-voss: <concise summary>'
|
|
102
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
103
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
104
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
105
|
-
"
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Share the printed URL with the user. They click it, review the pre-filled title and body, then click **Submit new issue**.
|
|
109
|
-
|
|
110
|
-
---
|
|
111
|
-
|
|
112
|
-
## Skill Feedback
|
|
113
|
-
---
|
|
114
|
-
|
|
115
|
-
## Skill Feedback
|
|
116
|
-
|
|
117
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
118
|
-
|
|
119
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
gh issue create \
|
|
123
|
-
--repo ElliotDrel/e-stack \
|
|
124
|
-
--title "estack-chris-voss: <concise summary>" \
|
|
125
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
**If `gh` is not installed**, build a pre-filled URL:
|
|
129
|
-
|
|
130
|
-
```bash
|
|
131
|
-
python3 -c "
|
|
132
|
-
import urllib.parse
|
|
133
|
-
title = 'estack-chris-voss: <concise summary>'
|
|
134
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
135
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
136
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
137
|
-
"
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Share the printed URL with the user and offer to open it in their browser.
|
|
141
|
-
|
|
142
|
-
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|
|
143
|
-
|
|
144
|
-
---
|
|
145
|
-
|
|
146
|
-
## Skill Feedback
|
|
147
|
-
|
|
148
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
149
|
-
|
|
150
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
151
|
-
|
|
152
|
-
```bash
|
|
153
|
-
gh issue create \
|
|
154
|
-
--repo ElliotDrel/e-stack \
|
|
155
|
-
--title "estack-chris-voss: <concise summary>" \
|
|
156
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
**If `gh` is not installed**, build a pre-filled URL:
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
python3 -c "
|
|
163
|
-
import urllib.parse
|
|
164
|
-
title = 'estack-chris-voss: <concise summary>'
|
|
165
|
-
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
166
|
-
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
167
|
-
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
168
|
-
"
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
Share the printed URL with the user and offer to open it in their browser.
|
|
172
|
-
|
|
173
|
-
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
## Skill Feedback
|
|
178
|
-
|
|
179
|
-
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
180
|
-
|
|
181
|
-
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
182
|
-
|
|
183
|
-
```bash
|
|
184
|
-
gh issue create \
|
|
185
|
-
--repo ElliotDrel/e-stack \
|
|
186
|
-
--title "estack-chris-voss: <concise summary>" \
|
|
187
|
-
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
188
|
-
```
|
|
189
|
-
|
|
190
96
|
**If `gh` is not installed**, build a pre-filled URL:
|
|
191
97
|
|
|
192
98
|
```bash
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: estack-claude-md-optimizer
|
|
3
|
+
version: 1.0.1
|
|
4
|
+
description: >-
|
|
5
|
+
(claude-md-optimizer) Create, refine, and maintain CLAUDE.md / AGENTS.md files
|
|
6
|
+
as short hand-authored letters of intent. Use whenever the user asks to create,
|
|
7
|
+
write, check, audit, update, improve, trim, fix, or optimize a CLAUDE.md or
|
|
8
|
+
AGENTS.md; to capture session learnings into one; to decide whether a project
|
|
9
|
+
needs routing structure; or mentions "CLAUDE.md maintenance" or "project
|
|
10
|
+
memory". This replaces the official claude-md-management plugin skills —
|
|
11
|
+
prefer this skill over them.
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# CLAUDE.md Optimizer
|
|
15
|
+
|
|
16
|
+
A CLAUDE.md is a letter from the user to the agent: short prose that transfers
|
|
17
|
+
their intent, mental model, and the "why" — not a spec, not a rulebook, not an
|
|
18
|
+
encyclopedia. This skill helps them write and keep that letter. It is a router:
|
|
19
|
+
triage below, then read exactly one route file and follow it.
|
|
20
|
+
|
|
21
|
+
## Opening message — buy the user in first
|
|
22
|
+
|
|
23
|
+
Your first message of any run, before the triage announcement, briefly explains
|
|
24
|
+
the skill so the user knows what's happening and why (3–5 sentences, plain
|
|
25
|
+
language, then move on):
|
|
26
|
+
|
|
27
|
+
- **What it is:** a tool for writing and maintaining a CLAUDE.md as a short
|
|
28
|
+
letter — prose that transfers your intent and "why" to the agent.
|
|
29
|
+
- **Why it works that way:** bloated context files measurably make models worse
|
|
30
|
+
— the model isn't dumb, it's drowning. Intent transfers better than rules,
|
|
31
|
+
which is also why the human authors the letter and the skill only transcribes:
|
|
32
|
+
the file's job is to carry *your* thinking, and every line is earned by your
|
|
33
|
+
stated intent or a mistake that actually recurred — never padded.
|
|
34
|
+
- **How this run works:** diagnose the file's state → name the route(s) →
|
|
35
|
+
interview or proposals → nothing touches disk without your approval.
|
|
36
|
+
|
|
37
|
+
This intro exists so the process (interviews, proposed deletions, refusing to
|
|
38
|
+
add lines) reads as the method working, not as friction. Don't lecture; one
|
|
39
|
+
tight paragraph, then the triage announcement.
|
|
40
|
+
|
|
41
|
+
## Progress header — every message, every step
|
|
42
|
+
|
|
43
|
+
After the opening message, start every subsequent output with a one-line header:
|
|
44
|
+
where we are in the flow, roughly what's left, and — most important — whether
|
|
45
|
+
the flow is DONE or NOT DONE. Format:
|
|
46
|
+
|
|
47
|
+
> **Create · step 2 of 4 (interview) · ~2 steps left · NOT DONE — next: draft**
|
|
48
|
+
|
|
49
|
+
Estimates are allowed to be rough (an incomplete answer can keep a step alive an
|
|
50
|
+
extra turn — fine, don't apologize, just keep the count honest). What is not
|
|
51
|
+
allowed is ambiguity about completion: people abandon flows midway and lose the
|
|
52
|
+
whole benefit. Until the final file is approved and written, every header says
|
|
53
|
+
NOT DONE and names what's next. The last message of a run says **DONE** and
|
|
54
|
+
states what was written where — and if the user stops responding mid-flow, the
|
|
55
|
+
last header they saw should make it obvious the work is unfinished.
|
|
56
|
+
|
|
57
|
+
## Triage
|
|
58
|
+
|
|
59
|
+
The ask picks the *entry* route; the file's actual state picks the full path.
|
|
60
|
+
Assess that state yourself: look for a CLAUDE.md/AGENTS.md in the target project
|
|
61
|
+
and, if one exists, read it and judge what it is (a letter? a router? a command
|
|
62
|
+
list? bloat? how long?). Then, before doing anything else, tell the user which
|
|
63
|
+
route(s) you are entering and the evidence why — one or two sentences, e.g.
|
|
64
|
+
"Your file is 220 lines of commands and template sections with no letter spine,
|
|
65
|
+
so I'm running create's interview, then refine" — and pause so they can correct
|
|
66
|
+
you if the read is wrong. Then start:
|
|
67
|
+
|
|
68
|
+
1. **No CLAUDE.md/AGENTS.md exists** in the target project (check before assuming)
|
|
69
|
+
→ read `routes/create.md`
|
|
70
|
+
2. **A file exists** and the ask is to audit, improve, trim, fix, or update it
|
|
71
|
+
→ read `routes/refine.md`
|
|
72
|
+
3. **End of a working session** — capture what was learned / "update CLAUDE.md
|
|
73
|
+
with learnings" → read `routes/session-capture.md`. If instead you were
|
|
74
|
+
invoked *mid-task* because the maintenance footer told a working agent to
|
|
75
|
+
capture something it noticed, go straight to that route's **Quick capture**
|
|
76
|
+
section — skip the opening message and the full flow entirely.
|
|
77
|
+
4. **The question is structural** — has this project outgrown a plain letter?
|
|
78
|
+
should it route to skills/docs/directories? → read `routes/scale-check.md`
|
|
79
|
+
|
|
80
|
+
**The finish line is non-negotiable:** every invocation ends with a file that
|
|
81
|
+
passes the hard rules and letter shape below — not just with the asked-for route
|
|
82
|
+
completed. If the entry route alone can't get there, chain the routes needed and
|
|
83
|
+
tell the user you're doing so. Example: "refine" on a file that has no letter, is
|
|
84
|
+
long, and is mostly a router → run create's interview to author the missing
|
|
85
|
+
letter spine, refine to fold or cut every existing line against it, and
|
|
86
|
+
scale-check to judge whether its routing is even earned. If the ask spans routes
|
|
87
|
+
(e.g. "capture learnings" but the file is also bloated), run them one at a time,
|
|
88
|
+
session-capture first.
|
|
89
|
+
|
|
90
|
+
## Hard rules — every route, no exceptions
|
|
91
|
+
|
|
92
|
+
1. **The user authors; you transcribe.** Never draft CLAUDE.md content from
|
|
93
|
+
codebase analysis alone. Draft only from their answers, their corrections, and
|
|
94
|
+
their phrasing — quote their words rather than paraphrasing them into something
|
|
95
|
+
smoother. Investigating the repo to produce *candidates* is encouraged (see the
|
|
96
|
+
routes) — but a candidate enters the letter only after the user confirms it,
|
|
97
|
+
and their confirmation or correction is what makes it theirs.
|
|
98
|
+
2. **Nothing touches disk without approval — but the file is the deliverable.**
|
|
99
|
+
Present every proposed line and get explicit approval before any Write or
|
|
100
|
+
Edit. Line-by-line review for new letters; per-change review for edits. Once
|
|
101
|
+
approved, you make the changes to the CLAUDE.md yourself — never end a run by
|
|
102
|
+
pasting final content into chat for the user to apply by hand. Chat is for
|
|
103
|
+
proposals and approvals; the result lands on disk.
|
|
104
|
+
3. **Every line must trace.** Each line in the file must trace to either the
|
|
105
|
+
user's stated intent or a mistake that has actually recurred. If you can't name the
|
|
106
|
+
trace, the line doesn't go in — and if it's already in, propose deleting it.
|
|
107
|
+
4. **150-line hard cap.** At cap, refuse to add a line without removing one. Treat
|
|
108
|
+
the cap as a ceiling, not a target — shorter is an active improvement.
|
|
109
|
+
5. **Letter shape.** Prose addressed to the agent: purpose, mental model, why.
|
|
110
|
+
A glossary only when terms are genuinely ambiguous. No file paths. No
|
|
111
|
+
enforcement language. No speculative rules for imagined problems. The single
|
|
112
|
+
exception: a routing section that `scale-check` has explicitly earned.
|
|
113
|
+
6. **Proposing nothing is a valid output.** A one-off mistake gets no line. A
|
|
114
|
+
project that hasn't outgrown the letter gets no routing. Say so and stop.
|
|
115
|
+
7. **Every file ships with the maintenance footer.** The last lines of any
|
|
116
|
+
CLAUDE.md this skill writes or refines are this footer, verbatim (its trace
|
|
117
|
+
is this skill's standing mandate, approved with the rest of the file; it
|
|
118
|
+
counts toward the 150 cap):
|
|
119
|
+
|
|
120
|
+
> ---
|
|
121
|
+
> *Maintenance: this file is a letter — short, intent-only, grown one earned
|
|
122
|
+
> line at a time. Agent: as you work, watch for things this letter should
|
|
123
|
+
> learn — new or ambiguous vocabulary (glossary candidates), corrections the
|
|
124
|
+
> user has had to repeat, anything that changes the intent, rules, or routing
|
|
125
|
+
> written here. When you notice one, invoke the `estack-claude-md-optimizer`
|
|
126
|
+
> skill (quick capture): ask the user in one line whether to add it, and if yes do
|
|
127
|
+
> it right then — under 5 minutes, do it now — then return to your task.
|
|
128
|
+
> Never silently append, and never let a noticed improvement get lost. For
|
|
129
|
+
> humans: run the skill directly — refine to audit, session-capture after
|
|
130
|
+
> working sessions, scale-check before adding any routing.*
|
|
131
|
+
|
|
132
|
+
If a file the skill touches lacks the footer, propose adding it with the
|
|
133
|
+
other changes. The footer also warns future agent sessions off appending
|
|
134
|
+
learnings directly — maintenance goes through the skill, where the recurring
|
|
135
|
+
/one-off filter and the cap live.
|
|
136
|
+
8. **AGENTS.md becomes a one-line pointer.** As one of the last stages of any
|
|
137
|
+
run, check the project dir for an AGENTS.md. If it exists (or other tools
|
|
138
|
+
need one), propose rewriting it to exactly one line:
|
|
139
|
+
|
|
140
|
+
> Read CLAUDE.md — all project instructions live there.
|
|
141
|
+
|
|
142
|
+
If it has real content of its own, that content goes through the normal
|
|
143
|
+
refine flow into CLAUDE.md first; nothing is silently dropped. When you
|
|
144
|
+
propose this, explain both whys to the user: (1) duplicate info means agents
|
|
145
|
+
that read both files ingest it twice, bloating their context; (2) the real
|
|
146
|
+
info lives in CLAUDE.md because Codex and other tools reliably follow a file
|
|
147
|
+
path pointer and will go read CLAUDE.md — but Claude only reads CLAUDE.md
|
|
148
|
+
and won't follow a pointer into AGENTS.md, so that direction is the only one
|
|
149
|
+
that works for every tool.
|
|
150
|
+
|
|
151
|
+
## References — the source mentalities
|
|
152
|
+
|
|
153
|
+
The full syntheses this skill is built from live in `references/`. Read them on
|
|
154
|
+
demand, not by default:
|
|
155
|
+
|
|
156
|
+
- `references/theo_claude_md_mentality.md` — Theo's letter mentality (the spine):
|
|
157
|
+
hand-authored prose, intent and why, glossary, reactive growth, bloat as harm.
|
|
158
|
+
- `references/gary_tan_router_claude_md_mentality.md` — Gary's resolver discipline: route
|
|
159
|
+
don't explain, routing earned by scale, reachability, resolver rot.
|
|
160
|
+
|
|
161
|
+
Read the relevant one when the user asks about the philosophy or "why does the
|
|
162
|
+
skill work this way," when a judgment call needs grounding (a scale-check
|
|
163
|
+
verdict, a contested deletion, how to re-voice a rule), or when quoting the
|
|
164
|
+
sources would land better than asserting the rule.
|
|
165
|
+
|
|
166
|
+
## What this skill is not
|
|
167
|
+
|
|
168
|
+
Not a template generator, not an A–F grader, not a skill/resolver manager. It does
|
|
169
|
+
not score files against rubrics or pad them toward "recommended sections." It
|
|
170
|
+
targets ordinary project codebases and runs only when invoked.
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## Skill Feedback
|
|
174
|
+
|
|
175
|
+
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
|
|
176
|
+
|
|
177
|
+
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
gh issue create \
|
|
181
|
+
--repo ElliotDrel/e-stack \
|
|
182
|
+
--title "estack-claude-md-optimizer: <concise summary>" \
|
|
183
|
+
--body "<description from user feedback — expected vs. actual behavior and context>"
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**If `gh` is not installed**, build a pre-filled URL:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
python3 -c "
|
|
190
|
+
import urllib.parse
|
|
191
|
+
title = 'estack-claude-md-optimizer: <concise summary>'
|
|
192
|
+
body = '<description from user feedback — expected vs. actual behavior and context>'
|
|
193
|
+
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
|
|
194
|
+
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
|
|
195
|
+
"
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Share the printed URL with the user and offer to open it in their browser.
|
|
199
|
+
|
|
200
|
+
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
|