@codegiveness/kernel-prompt 0.1.3 → 0.3.0

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.
Files changed (9) hide show
  1. package/CHANGELOG.md +49 -1
  2. package/LICENSE +0 -0
  3. package/README.md +33 -85
  4. package/package.json +5 -23
  5. package/skills/kernel-prompt/SKILL.md +35 -0
  6. package/bin/kernel-prompt.mjs +0 -105
  7. package/skills/engineering/kernel-prompt/EXAMPLE.md +0 -82
  8. package/skills/engineering/kernel-prompt/REFORMULATIONS.md +0 -38
  9. package/skills/engineering/kernel-prompt/SKILL.md +0 -75
package/CHANGELOG.md CHANGED
@@ -1,4 +1,52 @@
1
- # @codegiveness/kernel-prompt
1
+ # Kernel Prompt
2
+
3
+ ## [0.3.0] - 2026-10-10
4
+
5
+ ### Changed
6
+
7
+ - Redesign the skill as a self-contained adaptive prompt editor, with a focused trigger, lightweight KERNEL considerations, and task-specific decision and completion boundaries.
8
+ - Add a conditional questioning method adapted from grilling and brainstorming: look facts up rather than asking, ask only decisions the user alone can make, in rounds of independent questions led by recommended answers, through the harness's question tool when available. Add a recipient check before handoff, anti-goals, non-goals, report-back expectations, and a short list of consequential calls made. Clear requests still get a prompt without questions.
9
+ - Consolidate the README around a balanced KERNEL philosophy, the guiding article, ordinary chat use, and optional Git-based installation.
10
+ - Replace `CLAUDE.md` and the agent-guidance link/pointer arrangement with a standalone, harness-neutral `AGENTS.md`.
11
+ - Deprecate npm versions 0.1.0–0.1.3 and 0.2.0 with a migration notice while preserving downloads and version tags; they carry historical skill content, and 0.1.x a removed CLI.
12
+ - Restore npm distribution with a minimal manifest that ships only the skill files, published through npm staged publishing with two-factor approval.
13
+
14
+ ### Fixed
15
+
16
+ - Clarify the skill's discovery description and selection boundary: document or guidance reviews do not become prompt-design requests merely because they discuss AI instructions or ask for wording suggestions. Preserve prompt improvement, composition, design feedback, and AI handoffs.
17
+ - Deliver a prompt, not the task's result, when the skill is invoked directly with text that reads as a task. The previous selection guidance ("follow that request directly") led models to fix code, answer questions, or write the requested content instead; facts may still be gathered to inform the prompt.
18
+
19
+ ### Removed
20
+
21
+ - Remove the `.agents/` architecture decision record and its incoming documentation links.
22
+ - Remove Changesets configuration, scripts, and dependencies.
23
+ - Remove Claude Code plugin packaging, installation instructions, and plugin-specific CI and release checks.
24
+ - Remove the separate `.out-of-scope/` checklist and its incoming documentation link.
25
+ - Remove `docs/`, including old audit artifacts, audit guidance, and improvement history.
26
+ - Remove `node_modules/` and the automated npm publishing workflow; npm releases are staged manually.
27
+ - Remove `EXAMPLE.md` and `REFORMULATIONS.md`; keep one short delegation contrast inside `SKILL.md`.
28
+ - Remove `CONTEXT.md`; keep the project explanation in the README and behavior in `SKILL.md`.
29
+
30
+ ## [0.2.0] - 2026-09-13
31
+
32
+ ### Changed
33
+
34
+ - Redesign KERNEL around intent preservation, evidence, consequential decisions, task boundaries, meaningful success checks, and a portable handoff.
35
+ - Replace mandatory one-paragraph output and visible per-clause audits with ready, clarification, and provisional response states that honor the requested format and language.
36
+ - Preserve fresh-information requests, multi-part deliverables, exact task inputs, and later corrections. Keep unknowns explicit rather than inventing versions, paths, diagnoses, or constraints.
37
+ - Replace meaning-changing reformulations and fabricated grounding examples with faithful repairs and examples covering missing evidence, conflicting constraints, no-question requests, quoted instructions, and strict formats.
38
+ - Reduce core instruction overhead and check each added obligation against the request, necessary completion criteria, or host requirements. Add examples distinguishing execution limits from planning, verbatim task inputs from transformed outputs, and unresolved permission from approval already granted.
39
+ - Check whether an existing prompt needs repair before rewriting it. Keep clear clauses unchanged, scope delegated choices, distinguish outcome checks from extra activity reports, and avoid repeated template payloads unless repetition is required by the task or format.
40
+ - Check surrounding task context before returning a draft unchanged. Carry supplied facts, input locations, access, and approval into the handoff while keeping refiner-only directions separate. Fill delegated choices with concise values instead of developing unassigned creative or implementation details.
41
+ - Add an LLM-consumer-only audit agreement and durable improvement history, with saved instruction snapshots, model outputs, and unresolved consumer difficulties. Keep historical scores separate from accuracy claims and installer verification.
42
+ - Flatten the canonical skill directory to `skills/kernel-prompt/`, matching the single-skill layout of `codegiveness/shared-understanding`. Make `npx skills@latest add codegiveness/kernel-prompt` the primary installation route; preserve the skill's prose unchanged by this migration.
43
+ - Remove the custom npm install/update command, development helper scripts, and obsolete installer tests. Update package metadata, plugin paths, CI, release checks, and current documentation for the flat layout and Skills CLI installation.
44
+ - Retire JavaScript CodeQL analysis after removing the last executable source; verify real Skills CLI installation in CI instead.
45
+
46
+ ### Fixed
47
+
48
+ - Preserve the action, object, and conditions of prohibitions instead of broadening execution limits into planning bans or reopening granted approval. Distinguish task-input preservation from unrequested output-format restrictions.
49
+ - Synchronize the stale lockfile package version with the existing 0.1.3 package and plugin versions, without changing dependency resolutions; check all version fields in CI.
2
50
 
3
51
  ## [0.1.3] - 2026-07-26
4
52
 
package/LICENSE CHANGED
File without changes
package/README.md CHANGED
@@ -1,111 +1,59 @@
1
- # Kernel — a prompt stripped to what works
1
+ # Kernel Prompt
2
2
 
3
- [![skills.sh](https://skills.sh/b/codegiveness/kernel-prompt)](https://skills.sh/codegiveness/kernel-prompt)
4
- [![npm version](https://img.shields.io/npm/v/@codegiveness/kernel-prompt.svg?style=flat-square)](https://www.npmjs.com/package/@codegiveness/kernel-prompt)
5
- [![npm downloads](https://img.shields.io/npm/dm/@codegiveness/kernel-prompt.svg?style=flat-square)](https://www.npmjs.com/package/@codegiveness/kernel-prompt)
6
- [![MIT License](https://img.shields.io/npm/l/@codegiveness/kernel-prompt.svg?style=flat-square)](https://github.com/codegiveness/kernel-prompt/blob/main/LICENSE)
7
- [![CI](https://github.com/codegiveness/kernel-prompt/actions/workflows/ci.yml/badge.svg)](https://github.com/codegiveness/kernel-prompt/actions/workflows/ci.yml)
8
- [![CodeQL](https://github.com/codegiveness/kernel-prompt/actions/workflows/codeql.yml/badge.svg)](https://github.com/codegiveness/kernel-prompt/actions/workflows/codeql.yml)
3
+ `kernel-prompt` is a small, harness-neutral prose skill for improving an existing prompt or composing one from a goal. It rewrites and reorganizes where useful while preserving intent. It designs the prompt, not the underlying task's result.
9
4
 
10
- Six cuts that turn a vague request into a prompt that lands on first try.
5
+ Select it for requested prompt design, including prompt-design feedback or instructions to hand off to another AI. Reviewing documents or collaboration guidance—even with wording suggestions—is not by itself a match. Asking to turn that guidance into a system prompt is.
11
6
 
12
- ## Quickstart (30-second setup)
7
+ ## Use it
13
8
 
14
- 1. Run the skills.sh installer:
9
+ In an LLM chat, provide the contents of [SKILL.md](skills/kernel-prompt/SKILL.md) as guidance alongside your request. No installation is needed. With the skill available, ask:
15
10
 
16
- ```bash
17
- npx skills@latest add codegiveness/kernel-prompt
11
+ ```text
12
+ Use kernel-prompt to improve this request:
13
+ [your goal or draft, with relevant context and constraints]
18
14
  ```
19
15
 
20
- 2. Pick the skill, and which coding agent you want to install it on (Claude Code, Codex, OpenCode, or others).
21
-
22
- 3. Bam — you're ready to go. The skill is prose; nothing compiles.
23
-
24
- ## Install via npm
16
+ Expect a usable prompt, a short round of questions when a decision only you can make matters, or a draft with explicit unknowns when answers are unavailable. Invoking the skill with text that reads as a task—"fix the failing login test"—yields a prompt for that task, not the fix. Questions use the harness's question tool when one exists, each led by a recommended answer. Ask for explanations or alternatives when wanted.
25
17
 
26
- Prefer a managed npm install you control by hand?
27
-
28
- ```bash
29
- npm install -g @codegiveness/kernel-prompt
30
- kernel-prompt install # symlinks the skill into ~/.claude/skills and ~/.agents/skills
31
- ```
18
+ ## The idea
32
19
 
33
- Or copy the three files from `skills/engineering/kernel-prompt/` into your project's skill directory — the skill is prose, nothing compiles.
20
+ A kernel makes the intended outcome, relevant context, boundaries, and completion conditions clear. Add detail where it helps the task; leave unassigned execution choices open. Facts are looked up, not asked; only decisions the user alone can make become questions. Before handing over, the draft is read as its recipient would read it—capable, without the conversation, unable to ask.
34
21
 
35
- To stay current:
22
+ **KERNEL** is a mnemonic, not a mandatory sequence or template:
36
23
 
37
- ```bash
38
- kernel-prompt update # npm install -g @codegiveness/kernel-prompt@latest
39
- ```
24
+ - **K**eep intent.
25
+ - **E**stablish what is known.
26
+ - **R**esolve consequential ambiguity.
27
+ - **N**ame the work and boundaries.
28
+ - **E**xpress success.
29
+ - **L**ay out the handoff.
40
30
 
41
- ## Install as a Claude Code plugin
31
+ The guiding reference is OpenAI's [Rethinking skills and prompts for GPT-6 Astra](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra). Revisit accumulated instructions, avoid unnecessary recipes, and adapt guidance to the task and model. The article's model-specific advice is not a universal rule; clearer prompts do not guarantee correct answers.
42
32
 
43
- This skill also ships as a native Claude Code plugin:
33
+ The questioning adapts Matt Pocock's [grilling](https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling) (rounds of independent decisions with recommended answers; facts versus decisions) and the recipient check adapts the builder check in obra's [brainstorming](https://github.com/obra/superpowers/tree/main/skills/brainstorming), scaled down so a clear request gets no questions.
44
34
 
45
- ```
46
- /plugin marketplace add codegiveness/kernel-prompt
47
- /plugin install kernel-prompt@codegiveness
48
- ```
35
+ ## Optional installation
49
36
 
50
- Or from your shell:
37
+ For harnesses supporting [Agent Skills](https://agentskills.io/specification), install with the [Skills CLI](https://github.com/vercel-labs/skills):
51
38
 
52
39
  ```bash
53
- claude plugin marketplace add codegiveness/kernel-prompt
54
- claude plugin install kernel-prompt@codegiveness
40
+ npx skills@latest add codegiveness/kernel-prompt
55
41
  ```
56
42
 
57
- Three ways to install, three philosophies:
58
-
59
- - **[skills.sh](https://skills.sh/codegiveness/kernel-prompt)** copies the skill into your project so you can hack on it and make it your own.
60
- - **npm** installs the managed package globally and symlinks it into every agent harness you use.
61
- - **The plugin** keeps it as a read-only, always-current bundle you don't edit — best when you just want the skill to work and follow along as it evolves.
62
-
63
- ## Why This Skill Exists
43
+ Choose the harness and installation scope when prompted. Add `--copy` if symlinks are unsupported. To install this working copy instead of the GitHub revision, run `npx skills@latest add .` from the repository root.
64
44
 
65
- > "No-one knows exactly what they want."
66
- >
67
- > David Thomas & Andrew Hunt, [The Pragmatic Programmer](https://www.amazon.co.uk/Pragmatic-Programmer-Anniversary-Journey-Mastery/dp/B0833F1T3V)
45
+ You can also copy `skills/kernel-prompt/` into your harness's skill location. Only `SKILL.md` is needed. The skill has no application runtime, build step, or project dependencies; the optional installer is external tooling.
68
46
 
69
- Every prompt-engineering failure mode traces back to one root cause: the request was vague. The agent filled the vagueness with its own priors, the priors were wrong, and the output missed. The fix is not a longer prompt — it is a tighter one. A prompt where every clause passes a two-reader test: would two different readers produce outputs matching in type and scope?
47
+ ## npm package
70
48
 
71
- > "The best modules are deep. They allow a lot of functionality to be accessed through a simple interface."
72
- >
73
- > John Ousterhout, [A Philosophy Of Software Design](https://www.amazon.co.uk/Philosophy-Software-Design-2nd/dp/173210221X)
49
+ The skill is also published as [`@codegiveness/kernel-prompt`](https://www.npmjs.com/package/@codegiveness/kernel-prompt). The package contains only the skill files, with the skill at `skills/kernel-prompt/SKILL.md`; it has no CLI or runtime. Use it when you want a versioned, pinnable copy:
74
50
 
75
- `kernel-prompt` is a deep module. Its interface is one paragraph; its behaviour is a six-letter pass — **K**eep it simple, **E**asy to verify, **R**eproducible, **N**arrow scope, **E**xplicit constraints, **L**ogical structure — plus an exhaustive vague-phrasing sweep. That paragraph carries five substances as flowing prose: **context** (grounded codebase symbols), **task** (the operation to perform), **constraints** (type, scope, limits), **format** (the deliverable shape), and **verify** (a checkable success criterion). You hand it a vague request, it returns a paragraph that lands. The simplicity is the point — the depth is in the cuts.
76
-
77
- > "With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model."
78
- >
79
- > Eric Evans, [Domain-Driven Design](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215)
80
-
81
- The pass grounds vague terms to concrete codebase symbols before it writes. "The auth service" becomes `refreshToken (src/auth/tokens.ts:42)`. The paragraph carries the grounded vocabulary, not the user's original phrasing — so two readers see the same code, not the same ambiguity.
82
-
83
- The skill is model-invoked: any agent can reach for it when the task fits, and a user can call it directly. It has no `disable-model-invocation` flag — that's deliberate. A kernel'd prompt is the input every other skill wants.
84
-
85
- ## Before / after
86
-
87
- **Vague input:**
88
-
89
- > Our auth service has a token refresh bug — users get logged out. Fix it, add a test that catches the regression, and update the runbook so on-call knows what to do.
90
-
91
- **Kernel'd output (one paragraph):**
92
-
93
- > `refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh, breaking `TokenStore` (src/auth/store.ts:15); patch `refreshToken` so it stops dropping sessions on refresh failure, add a `bun test` regression that fails before the fix and passes after, and update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each), shipping as one PR — TypeScript strict, no `as any`.
94
-
95
- The vague input names no symbols; the output grounds every term in a file and function, attaches a checkable success criterion, and carries its constraints inline. That's one pass — six cuts, one sweep, one paragraph.
96
-
97
- ## Reference
98
-
99
- The skill splits on one axis — who can invoke it. **User-invoked** skills are reachable only when you type them; their job is to orchestrate. **Model-invoked** skills can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. `kernel-prompt` is model-invoked.
51
+ ```bash
52
+ npm install @codegiveness/kernel-prompt
53
+ ```
100
54
 
101
- | Skill | Invocation | Description |
102
- |---|---|---|
103
- | [kernel-prompt](./skills/engineering/kernel-prompt/SKILL.md) | Model-invoked | Kernel a prompt — refine or compose it into one paragraph that lands on first try. |
55
+ Then copy `node_modules/@codegiveness/kernel-prompt/skills/kernel-prompt/` into your harness's skill location. Releases are staged with `npm stage publish` and go live only after a maintainer approves them with two-factor authentication.
104
56
 
105
- ### Files
57
+ Versions 0.1.0 through 0.2.0 remain deprecated: they carry historical skill content, and 0.1.x also shipped an `install`/`update` CLI that no longer exists. Replace only your existing Kernel Prompt skill with the current `SKILL.md`, preserving local edits and unrelated instructions; deprecation does not remove installed files or update copied instructions.
106
58
 
107
- | File | Purpose |
108
- |---|---|
109
- | [`SKILL.md`](./skills/engineering/kernel-prompt/SKILL.md) | The KERNEL pass — six cuts (K-E-R-N-E-L) and the vague-phrasing sweep |
110
- | [`EXAMPLE.md`](./skills/engineering/kernel-prompt/EXAMPLE.md) | A full disclosed pass: grounding, combining, six letters, sweep with per-clause verdicts |
111
- | [`REFORMULATIONS.md`](./skills/engineering/kernel-prompt/REFORMULATIONS.md) | Seven named patterns for repairing clauses that fail the two-reader test |
59
+ [MIT license](LICENSE)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@codegiveness/kernel-prompt",
3
- "version": "0.1.3",
4
- "description": "Kernel — a prompt stripped to what works. Six cuts that turn a vague request into a prompt that lands on first try.",
3
+ "version": "0.3.0",
4
+ "description": "Agent skill that turns rough requests and drafts into clear prompts for other agents, asking only the decisions that change the result.",
5
5
  "license": "MIT",
6
6
  "author": "codegiveness",
7
7
  "repository": {
@@ -14,36 +14,18 @@
14
14
  },
15
15
  "keywords": [
16
16
  "prompt-engineering",
17
- "kernel",
18
17
  "prompt",
19
18
  "skill",
19
+ "agent-skills",
20
20
  "agent",
21
- "claude-code",
22
- "opencode",
23
- "codex",
24
- "refinement"
21
+ "kernel"
25
22
  ],
26
23
  "publishConfig": {
27
24
  "access": "public",
28
25
  "registry": "https://registry.npmjs.org/"
29
26
  },
30
- "bin": {
31
- "kernel-prompt": "bin/kernel-prompt.mjs"
32
- },
33
27
  "files": [
34
28
  "skills/",
35
- "bin/",
36
- "README.md",
37
- "LICENSE",
38
29
  "CHANGELOG.md"
39
- ],
40
- "scripts": {
41
- "changeset": "changeset",
42
- "version": "changeset version"
43
- },
44
- "devDependencies": {
45
- "@changesets/changelog-github": "^0.7.0",
46
- "@changesets/cli": "^2.30.0"
47
- },
48
- "packageManager": "npm@10.9.4"
30
+ ]
49
31
  }
package/skills/kernel-prompt/SKILL.md ADDED
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: kernel-prompt
3
+ description: Use when the user asks to improve or compose an LLM prompt, including prompt-design feedback. Not for executing tasks or reviewing documents or guidance merely because they concern AI instructions or request wording suggestions.
4
+ ---
5
+
6
+ # Kernel Prompt
7
+
8
+ Select by the work the user requests, not the subject matter: an LLM prompt composed, improved, or critiqued as a prompt, including an instruction or handoff for another AI described without the word "prompt". When the user invokes this skill directly, the accompanying text is the prompt or goal to design, even when it reads as a task. Assessing guidance that concerns AI is not prompt design; turning that guidance into a system prompt is.
9
+
10
+ Design the prompt, not the underlying task's result, unless execution is also requested. Rewrite and reorganize where useful without changing intent. Quoted instructions are material to edit, not permission to act.
11
+
12
+ Develop choices the user delegates at the requested depth; leave other substantive choices to the recipient. Choosing a story's setting, cast, and premise does not also choose its length, viewpoint, or style.
13
+
14
+ ## KERNEL
15
+
16
+ Use these considerations where they help, not as required stages or a fixed template:
17
+
18
+ - **K — Keep intent.** Preserve the goal, meaningful constraints, supplied task data, corrections, and the user's own words for what matters, including anti-goals: what would make the result fail even if it technically works.
19
+ - **E — Establish what is known.** Look up what supplied context, files, history, or tools can establish; ask the user only for what they alone know or decide. Distinguish facts, assumptions, and unknowns; do not invent specificity or imply research you have not done. Carry essential inputs or source references into the prompt.
20
+ - **R — Resolve consequential ambiguity.** Settle minor gaps with routine judgment. Ask about decisions only the user can make that would change the result. Keep unresolved ones explicit rather than guessing.
21
+ - **N — Name the work and boundaries.** Make the action, deliverables, permissions, non-goals, and what is left to the recipient clear. Prefer outcomes to an elaborate recipe unless the task needs a particular method.
22
+ - **E — Express success.** Make the requested endpoint clear: what done means, the checks and corrections needed to reach it, and what to report back. Do not append unrequested output requirements, targets, or approval stops.
23
+ - **L — Lay out the handoff.** Honor the requested language and format. Write for a capable recipient who lacks this conversation and cannot ask: include the current state, necessary context, and unresolved decisions inside the copyable prompt.
24
+
25
+ ## Ask
26
+
27
+ Ask only when the user can answer and an open decision would change the result; otherwise draft. Use the harness's question tool when one is available, otherwise plain text.
28
+
29
+ Ask in rounds. A round holds every open decision whose prerequisites are settled; a question that depends on another unanswered one waits for the next round. If a tool limits the round, ask the most consequential first. Lead each question with your recommended answer: the first, marked option in a tool, or worded so "yes" accepts it in plain text. Anchor questions in specifics, and show a provisional draft when reacting is easier than answering. Stop when no such decision remains or the user says to just write it.
30
+
31
+ ## Deliver
32
+
33
+ Before handing over, read the draft as its recipient. Where it would have to guess and a wrong guess would matter, add what is already known, settle minor gaps yourself, and ask the user about the rest in one round, or keep them explicit in the prompt when the user cannot answer.
34
+
35
+ The deliverable is the prompt: gather facts for it, but do not perform its task unless asked. Usually return only the usable prompt, followed by a short list of any consequential calls you made so the user can reject them. Include explanations or alternatives when requested. Check for lost intent, invented details, and unnecessary instructions; do not append a separate layer of execution advice. Leave an effective prompt alone when a change would add no value.
package/bin/kernel-prompt.mjs DELETED
@@ -1,105 +0,0 @@
1
- #!/usr/bin/env node
2
- // kernel-prompt — thin npm wrapper for install / update.
3
- // The skill itself is prose (skills/engineering/kernel-prompt/*.md); this script
4
- // only symlinks the skill into the local harness directories or pulls the
5
- // latest version via npm.
6
-
7
- import { execSync } from "node:child_process";
8
- import { existsSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
9
- import { dirname, join, resolve } from "node:path";
10
- import { homedir } from "node:os";
11
-
12
- const PKG = "@codegiveness/kernel-prompt";
13
- const SKILL_NAME = "kernel-prompt";
14
-
15
- // Resolve the skill source relative to this bin file's installed location.
16
- // npm installs the package so that bin/kernel-prompt.mjs sits at <pkg-root>/bin/.
17
- const PKG_ROOT = resolve(dirname(new URL(import.meta.url).pathname), "..");
18
- const SKILL_SRC = join(PKG_ROOT, "skills", "engineering", SKILL_NAME);
19
-
20
- const DESTS = [
21
- join(homedir(), ".claude", "skills"),
22
- join(homedir(), ".agents", "skills"),
23
- ];
24
-
25
- function linkSkill() {
26
- if (!existsSync(SKILL_SRC)) {
27
- console.error(`error: skill source not found at ${SKILL_SRC}`);
28
- console.error(" the npm install may be corrupt; reinstall with:");
29
- console.error(` npm install -g ${PKG}`);
30
- process.exit(1);
31
- }
32
-
33
- for (const dest of DESTS) {
34
- // Bail if dest is itself a symlink into the package — would pollute the install.
35
- if (existsSync(dest)) {
36
- try {
37
- const resolved = realpathSync(dest);
38
- if (resolved.startsWith(PKG_ROOT)) {
39
- console.error(`error: ${dest} is a symlink into the package (${resolved}).`);
40
- console.error(` Remove it (rm "${dest}") and re-run.`);
41
- process.exit(1);
42
- }
43
- } catch {
44
- // Not a symlink, or unreadable — proceed.
45
- }
46
- }
47
-
48
- mkdirSync(dest, { recursive: true });
49
- const target = join(dest, SKILL_NAME);
50
-
51
- if (existsSync(target) || isSymlink(target)) {
52
- try { rmSync(target, { recursive: true, force: true }); } catch {}
53
- }
54
-
55
- try {
56
- symlinkSync(SKILL_SRC, target);
57
- console.log(`linked ${SKILL_NAME} -> ${SKILL_SRC} (${dest})`);
58
- } catch (err) {
59
- console.error(`warn: could not link into ${dest}: ${err.message}`);
60
- }
61
- }
62
- }
63
-
64
- function isSymlink(p) {
65
- try { readlinkSync(p); return true; } catch { return false; }
66
- }
67
-
68
- function update() {
69
- console.log(`Updating ${PKG}...`);
70
- try {
71
- execSync(`npm install -g ${PKG}@latest`, { stdio: "inherit" });
72
- console.log(`✅ ${PKG} updated.`);
73
- } catch (err) {
74
- console.error(`❌ npm install failed: ${err.message}`);
75
- process.exit(1);
76
- }
77
- }
78
-
79
- const cmd = process.argv[2];
80
-
81
- switch (cmd) {
82
- case "install":
83
- case "link":
84
- linkSkill();
85
- break;
86
- case "update":
87
- update();
88
- break;
89
- case undefined:
90
- case "help":
91
- case "--help":
92
- case "-h":
93
- console.log(`kernel-prompt — install or update the kernel-prompt skill
94
-
95
- usage:
96
- kernel-prompt install symlink the skill into ~/.claude/skills and ~/.agents/skills
97
- kernel-prompt update pull the latest version via npm
98
- kernel-prompt help show this help
99
- `);
100
- break;
101
- default:
102
- console.error(`unknown command: ${cmd}`);
103
- console.error("run `kernel-prompt help` for usage.");
104
- process.exit(2);
105
- }
package/skills/engineering/kernel-prompt/EXAMPLE.md DELETED
@@ -1,82 +0,0 @@
1
- # Worked example
2
-
3
- Disclosed reference for [`kernel-prompt`](SKILL.md). A full pass: grounding, combining a multi-goal request into one prompt, the six-letter pass, and the exhaustive vague-phrasing sweep with per-clause verdicts.
4
-
5
- ## Input (vague, multi-goal request)
6
-
7
- > Our auth service has a token refresh bug — users get logged out. Fix it, add a test that catches the regression, and update the runbook so on-call knows what to do.
8
-
9
- ## Grounding
10
-
11
- Input references "auth service," "token refresh," and "runbook" — all vague. Explored the codebase and pinned each to a concrete symbol:
12
-
13
- - "token refresh bug" → `refreshToken` (src/auth/tokens.ts:42)
14
- - "users get logged out" → `TokenStore` (src/auth/store.ts:15) drops sessions on refresh failure
15
- - "runbook" → `docs/runbooks/auth.md`
16
-
17
- ## Combining vs. chaining
18
-
19
- Three sub-goals: fix, test, docs. Test whether they combine:
20
- - Feed linearly? Yes — fix first, then test the fix, then document the fix.
21
- - Share context + constraints + verify? Yes — same auth module, same bug.
22
- - One deliverable? Yes — one PR (code + test + doc update).
23
-
24
- → Combine into one prompt.
25
-
26
- ## The KERNEL pass
27
-
28
- **K — Keep it simple.**
29
- - _Before:_ "Fix the token refresh bug, add a regression test, update the runbook"
30
- - _After:_ "Fix the token refresh bug in `refreshToken` (src/auth/tokens.ts:42), add a test that reproduces the bug before the fix, and update `docs/runbooks/auth.md` with the symptom and resolution."
31
-
32
- **E — Easy to verify.**
33
- - _Before:_ (none)
34
- - _After:_ "Test fails before the fix, passes after. Runbook entry has Symptom, Cause, Fix, Verification sections."
35
-
36
- **R — Reproducible.**
37
- - _unchanged_ — no temporal references in the input.
38
-
39
- **N — Narrow scope.**
40
- - _unchanged_ — combined into one deliverable (one PR). Sub-goals feed linearly and share context.
41
-
42
- **E — Explicit constraints.**
43
- - _Before:_ (none)
44
- - _After:_ "TypeScript strict, no `as any`. Test via `bun test`. Runbook update under 200 words per section."
45
-
46
- **L — Logical structure.**
47
- - _Before:_ one sentence
48
- - _After:_ one paragraph carrying context, task, constraints, format, and verify as flowing prose (below)
49
-
50
- ## Drafted prompt (before sweep)
51
-
52
- ```
53
- `refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh, breaking `TokenStore` (src/auth/store.ts:15); patch it so refresh stops dropping sessions, add a `bun test` regression that fails before the fix and passes after, and update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each), shipping as one PR — TypeScript strict, no `as any`.
54
- ```
55
-
56
- ## Vague-phrasing sweep
57
-
58
- Numbered list, one row per content clause, every clause in the paragraph:
59
-
60
- 1. "`refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh" — same file, same bug. **Passes.**
61
- 2. "breaking `TokenStore` (src/auth/store.ts:15)" — same file, same role. **Passes.**
62
- 3. "patch it so refresh stops dropping sessions" — two readers would diverge: one patches the specific line, another redesigns the refresh flow. **Fails** — applying **Name the operation**: "patch `refreshToken` so it stops dropping sessions on refresh failure."
63
- 4. "add a `bun test` regression that fails before the fix and passes after" — same operation, same tool, checkable criterion. **Passes.**
64
- 5. "update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each)" — same file, same scope, concrete limit. **Passes.**
65
- 6. "shipping as one PR — TypeScript strict, no `as any`" — same deliverable shape, same constraints. **Passes.**
66
-
67
- One clause reformulated (clause 3). Re-sweep the replacement: "patch `refreshToken` so it stops dropping sessions on refresh failure" — two readers would both modify `refreshToken` with the same target behavior (no session drop). Same kind (code patch), same coverage (the specific function). **Passes.**
68
-
69
- ## Final kernel'd prompt (after sweep)
70
-
71
- ```
72
- `refreshToken` (src/auth/tokens.ts:42) drops sessions on token refresh, breaking `TokenStore` (src/auth/store.ts:15); patch `refreshToken` so it stops dropping sessions on refresh failure, add a `bun test` regression that fails before the fix and passes after, and update `docs/runbooks/auth.md` with Symptom, Cause, Fix, and Verification sections (under 200 words each), shipping as one PR — TypeScript strict, no `as any`.
73
- ```
74
-
75
- ## Completion check
76
-
77
- 1. Every content clause in the paragraph passes the two-reader test, presented as a numbered list with per-clause verdict. One failure reformulated with pattern named. ✓
78
- 2. All six letters have before/after or unchanged with cited reason. ✓
79
- 3. Final prompt matches the L-letter form (one paragraph, all five substances present). ✓
80
- 4. Final paragraph re-swept — no vague terms introduced. ✓
81
-
82
- Pass complete.
package/skills/engineering/kernel-prompt/REFORMULATIONS.md DELETED
@@ -1,38 +0,0 @@
1
- # Reformulations
2
-
3
- Disclosed reference for [`kernel-prompt`](SKILL.md). When a content clause fails the two-reader test, apply one of the seven patterns below. The table shows concrete examples of each pattern in action.
4
-
5
- ## Patterns
6
-
7
- - **Assign a role** — name who is speaking or acting ("Act as a [specific role]")
8
- - **Name the lens** — specify the analytical frame ("Analyze through psychology, strategy, positioning")
9
- - **Set a concrete count** — replace "some" or "a few" with a number ("3 sentences", "5 ideas")
10
- - **Specify the audience** — name who the output is for ("for someone who already knows the basics")
11
- - **Name the operation** — replace a vague verb, modifier, or noun with the specific action ("Break this down", "Challenge this idea")
12
- - **Anchor to a real objection** — ground persuasion in a specific counterargument ("using this real objection: [X]")
13
- - **Add a structural constraint** — require a hook, format, or preservation rule ("with a hook in line 1")
14
-
15
- ## Examples
16
-
17
- Each row shows a vague clause and its specific replacement. Rows marked † are marketing-specific examples that illustrate the pattern, not universal reformulations.
18
-
19
- | Vague | Specific | Pattern |
20
- |---|---|---|
21
- | Explain it to me | Act as a [specific role] | Assign a role |
22
- | Give me information about… | Analyze this through psychology, strategy, and positioning | Name the lens |
23
- | What is it? | Analyze this through non-obvious angles — cost, risk, timing | Name the lens |
24
- | Make me a summary | Summarize this through the lens of trade-offs and alternatives | Name the lens |
25
- | Content ideas | Write it for someone who already knows the basics | Specify the audience |
26
- | Strategies for… | Break this concept down | Name the operation |
27
- | Tips for… | Challenge this idea | Name the operation |
28
- | Examples | Give me 3 examples with the pattern explained | Set a concrete count |
29
- | Benefits of… | Analyze the benefits through the lens of trade-offs and alternatives | Name the lens |
30
- | Make me more professional † | Make sure my client understands it in 5 seconds | Add a structural constraint |
31
- | Improve it | Score this against 3 named criteria: [your criteria] | Set a concrete count |
32
- | Make it shorter | Summarize it in 3 sentences without losing the main point | Set a concrete count |
33
- | Make it sound natural | Write it the way I speak, without jargon | Name the operation |
34
- | Write a post about… † | Write a post for [client] with a hook in line 1 | Specify the audience |
35
- | I need content ideas † | Give me 5 Reel ideas with the hook and format | Set a concrete count |
36
- | Fix this | Fix spelling and rhythm without changing my style | Name the operation |
37
- | Make it more persuasive | Rewrite this to overcome this real objection: [X] | Anchor to a real objection |
38
- | Write me a caption † | Give me 3 versions and tell me which one you recommend | Set a concrete count |
package/skills/engineering/kernel-prompt/SKILL.md DELETED
@@ -1,75 +0,0 @@
1
- ---
2
- name: kernel-prompt
3
- description: Kernel a prompt — refine or compose it into one paragraph that lands on first try. Use when the user wants to refine or compose a prompt. Other skills reach this when they need a kernel'd prompt as input.
4
- ---
5
-
6
- A **kernel** is a prompt stripped to what works. This skill runs the KERNEL pass — six cuts that turn a vague request into a prompt that lands on first try.
7
-
8
- ## Branches
9
-
10
- Two branches, same six letters, different input material:
11
- - **Refine** — input is an existing prompt. The "before" for each letter is that prompt's current state.
12
- - **Compose** — input is a task description. The "before" for each letter is what the task description provides for that letter; if it provides nothing, record _absent_ as the before.
13
-
14
- ## Grounding
15
-
16
- Before the pass, pin vague input terms to concrete symbols. When the input references a codebase, system, or API, explore it first (read files, query the index) and record a short grounding inventory: each vague term → the concrete symbol, file, or field it maps to. The pass writes the paragraph against this grounded vocabulary, not the user's original phrasing. Skip grounding only when the input is fully self-contained.
17
-
18
- ## Combining vs. chaining
19
-
20
- When the input spans multiple sub-goals, the default is to **combine** them into one prompt. Combine when the sub-goals:
21
- - Feed linearly (output of one is input to the next, in order).
22
- - Share the same context, constraints, and verify criteria.
23
- - Produce one deliverable (one document, one script, one spec).
24
-
25
- Split into a chain only when sub-goals produce different output types (a script vs. a doc) or need independent execution with different constraints. See [Chaining](#chaining).
26
-
27
- ## The KERNEL pass
28
-
29
- Run each letter in order. For each, produce a before/after note, or mark _unchanged_ with a reason that cites what's already in the prompt satisfying that letter (e.g., "unchanged — goal already stated as single sentence in line 1").
30
-
31
- **K — Keep it simple.** Strip to one clear goal. Cut context that doesn't serve it. If no goal is recoverable from the input, ask the user for one before continuing — do not invent one. This is the one legitimate pause point in the pass.
32
- - _Before:_ "I need help writing something about Redis"
33
- - _After:_ "Write a technical tutorial on Redis caching"
34
-
35
- **E — Easy to verify.** Attach a checkable success criterion. "Engaging" is not checkable; "3 code examples" is. If you can't verify success, the prompt can't deliver it.
36
-
37
- **R — Reproducible.** Remove temporal references ("current trends", "latest best practices"). Pin specific versions and exact requirements. The prompt should work next month.
38
-
39
- **N — Narrow scope.** One prompt, one deliverable. If the request genuinely cannot combine (see [Combining vs. chaining](#combining-vs-chaining)), split — see [Chaining](#chaining).
40
-
41
- **E — Explicit constraints.** List the exact scope: allowed libraries, max function length, output type, target audience. Keep a prohibition only as a hard guardrail you cannot phrase positively, and pair it with the positive target.
42
- - _Before:_ "Python code"
43
- - _After:_ "Python stdlib only; functions under 20 lines; output to stdout"
44
-
45
- **L — Logical structure.** Weave the prompt into **one paragraph** of prose carrying all five substances — context, task, constraints, format, verify — as flowing sentences joined by connectors (`;`, `,`, `and`).
46
- - _Before:_ scattered labeled lines — `Context: …` / `Task: …` / `Constraints: …`
47
- - _After:_ one paragraph — e.g. "`refreshToken` (src/auth/tokens.ts:42) drops sessions on refresh; patch it, add a failing-then-passing `bun test`, and update `docs/runbooks/auth.md` — TypeScript strict, no `as any`, one PR."
48
-
49
- ## Vague-phrasing sweep
50
-
51
- After the six letters, present the sweep as a numbered list — one row per content clause across the paragraph (the same five substances, now as sentences), every clause, not a representative sample. Each row states the clause and a pass/fail verdict. Apply the two-reader test per clause: would two different readers produce outputs matching in type and scope? "Matching" means same output kind (both produce a Python script, not one script and one prose) and same coverage (both cover the same scope, not one comprehensive and one partial). It does not mean byte-identical implementations.
52
-
53
- For each failing row, replace the vague clause using a pattern from [`REFORMULATIONS.md`](REFORMULATIONS.md), and name the pattern in the row: "Fails — applying **[Pattern Name]**: [replacement]". No silent reformulation.
54
-
55
- If no clause fails, state "No reformulations needed" — this is the common outcome when the paragraph is well-constructed and the input was grounded.
56
-
57
- ## Completion
58
-
59
- The pass is done when all four hold:
60
- 1. Every content clause in the paragraph passes the two-reader test, presented as a numbered list with a per-clause verdict. Each failing clause names the REFORMULATIONS.md pattern applied.
61
- 2. All six letters have a before/after note or _unchanged_ with a cited reason.
62
- 3. The final prompt matches the L-letter form (one paragraph, all five substances present).
63
- 4. The final paragraph passes its own two-reader sweep (re-swept after reformulation) — no vague verbs, vague nouns, or unscoped counts introduced in the output.
64
-
65
- ## Chaining
66
-
67
- Split a task into a chain only when combining fails the test in [Combining vs. chaining](#combining-vs-chaining). Each prompt in the chain gets its own KERNEL pass.
68
-
69
- Chain format: numbered list of prompts, each noting its dependency on the prior (`1. → 2. (feeds output of 1) → 3. (feeds output of 2)`).
70
-
71
- Re-pass rule: treat each prior prompt's output as input to the next. Re-run the vague-phrasing sweep on your own output before passing it forward — do not propagate vague terms across the chain.
72
-
73
- ## Worked example
74
-
75
- See [`EXAMPLE.md`](EXAMPLE.md) for a full pass: grounding, combining a multi-goal request into one prompt, the six-letter pass, and the exhaustive vague-phrasing sweep with per-clause verdicts.