@igorlau/dotagents 1.0.14 → 1.0.15

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 (91) hide show
  1. package/README.md +129 -35
  2. package/THIRD_PARTY_NOTICES.md +76 -2
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +8 -2
  6. package/dist/commands.js +60 -5
  7. package/dist/paths.js +1 -1
  8. package/dist/targets.js +3 -0
  9. package/package.json +2 -2
  10. package/plugin/.claude-plugin/plugin.json +10 -0
  11. package/plugin/agents/dot-implementer.md +38 -0
  12. package/plugin/agents/dot-reviewer.md +31 -0
  13. package/plugin/agents/dot-tester.md +33 -0
  14. package/plugin/hooks/check.mjs +92 -0
  15. package/plugin/hooks/hooks.json +24 -0
  16. package/plugin/rules/code-style.md +6 -0
  17. package/plugin/rules/comments.md +17 -0
  18. package/plugin/rules/comments.upstream.json +8 -0
  19. package/{content → plugin}/rules/ponytail.md +1 -1
  20. package/{content → plugin}/rules/ponytail.upstream.json +1 -1
  21. package/plugin/rules/writing.md +35 -0
  22. package/plugin/rules/writing.upstream.json +8 -0
  23. package/{content → plugin}/scaffold/AGENTS.md.tmpl +1 -0
  24. package/plugin/skills/dot-code-review/SKILL.md +71 -0
  25. package/plugin/skills/dot-code-review/UPSTREAM.json +8 -0
  26. package/plugin/skills/dot-code-review/references/maintainability.md +67 -0
  27. package/plugin/skills/dot-comments/SKILL.md +41 -0
  28. package/plugin/skills/dot-comments/UPSTREAM.json +8 -0
  29. package/{content → plugin}/skills/dot-commit/SKILL.md +7 -5
  30. package/plugin/skills/dot-correct/SKILL.md +43 -0
  31. package/plugin/skills/dot-correct/UPSTREAM.json +8 -0
  32. package/plugin/skills/dot-correct/agents/openai.yaml +5 -0
  33. package/plugin/skills/dot-debug/SKILL.md +125 -0
  34. package/plugin/skills/dot-debug/UPSTREAM.json +8 -0
  35. package/plugin/skills/dot-debug/references/loops.md +32 -0
  36. package/{content → plugin}/skills/dot-docs-writing/SKILL.md +15 -23
  37. package/{content → plugin}/skills/dot-docs-writing/references/formatting.md +26 -26
  38. package/{content → plugin}/skills/dot-docs-writing/references/global-and-accessible.md +9 -10
  39. package/{content → plugin}/skills/dot-docs-writing/references/word-list.md +4 -5
  40. package/plugin/skills/dot-flow/SKILL.md +75 -0
  41. package/plugin/skills/dot-flow/agents/openai.yaml +5 -0
  42. package/plugin/skills/dot-flow/references/inline.md +42 -0
  43. package/{content → plugin}/skills/dot-grill-me/SKILL.md +2 -2
  44. package/{content → plugin}/skills/dot-grill-me/UPSTREAM.json +1 -1
  45. package/plugin/skills/dot-grilling/SKILL.md +34 -0
  46. package/{content → plugin}/skills/dot-grilling/UPSTREAM.json +1 -1
  47. package/plugin/skills/dot-grilling/agents/openai.yaml +3 -0
  48. package/plugin/skills/dot-handoff/SKILL.md +20 -0
  49. package/{content → plugin}/skills/dot-handoff/UPSTREAM.json +1 -1
  50. package/plugin/skills/dot-implement/SKILL.md +65 -0
  51. package/plugin/skills/dot-implement/UPSTREAM.json +8 -0
  52. package/{content → plugin}/skills/dot-implement/references/typescript.md +29 -20
  53. package/{content → plugin}/skills/dot-plan/SKILL.md +15 -8
  54. package/plugin/skills/dot-plan/UPSTREAM.json +8 -0
  55. package/plugin/skills/dot-plan/references/entity-schemas.md +66 -0
  56. package/{content → plugin}/skills/dot-roadmap/SKILL.md +19 -12
  57. package/plugin/skills/dot-roadmap/UPSTREAM.json +8 -0
  58. package/plugin/skills/dot-roadmap/references/wide-refactor.md +3 -0
  59. package/plugin/skills/dot-testing/SKILL.md +48 -0
  60. package/plugin/skills/dot-testing/UPSTREAM.json +8 -0
  61. package/plugin/skills/dot-testing/references/http.md +15 -0
  62. package/plugin/skills/dot-testing/references/modes.md +32 -0
  63. package/plugin/skills/dot-testing/references/shared-state.md +3 -0
  64. package/{content → plugin}/skills/dot-testing/references/typescript.md +2 -2
  65. package/plugin/skills/dot-writing-for-agents/SKILL.md +54 -0
  66. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  67. package/plugin/skills/dot-writing-for-agents/references/pointers.md +27 -0
  68. package/plugin/skills/dot-writing-for-agents/references/skill-mechanics.md +22 -0
  69. package/plugin/skills/dot-writing-for-agents/references/steps.md +8 -0
  70. package/content/rules/comments.md +0 -15
  71. package/content/skills/dot-code-review/SKILL.md +0 -58
  72. package/content/skills/dot-debug/SKILL.md +0 -142
  73. package/content/skills/dot-debug/UPSTREAM.json +0 -8
  74. package/content/skills/dot-grilling/SKILL.md +0 -34
  75. package/content/skills/dot-grilling/agents/openai.yaml +0 -3
  76. package/content/skills/dot-handoff/SKILL.md +0 -20
  77. package/content/skills/dot-implement/SKILL.md +0 -52
  78. package/content/skills/dot-testing/SKILL.md +0 -44
  79. package/content/skills/dot-writing-for-agents/SKILL-MECHANICS.md +0 -22
  80. package/content/skills/dot-writing-for-agents/SKILL.md +0 -85
  81. package/content/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  82. /package/{content → plugin}/rules/core.md +0 -0
  83. /package/{content → plugin}/scaffold/.claude/settings.json.tmpl +0 -0
  84. /package/{content → plugin}/scaffold/.editorconfig.tmpl +0 -0
  85. /package/{content → plugin}/scaffold/.gitattributes.tmpl +0 -0
  86. /package/{content → plugin}/scaffold/CLAUDE.md.tmpl +0 -0
  87. /package/{content → plugin}/skills/dot-debug/agents/openai.yaml +0 -0
  88. /package/{content → plugin}/skills/dot-debug/scripts/hitl-loop.template.sh +0 -0
  89. /package/{content → plugin}/skills/dot-grill-me/agents/openai.yaml +0 -0
  90. /package/{content → plugin}/skills/dot-handoff/agents/openai.yaml +0 -0
  91. /package/{content → plugin}/skills/dot-writing-for-agents/agents/openai.yaml +0 -0
@@ -0,0 +1,32 @@
1
+ # Modes
2
+
3
+ Mode details for the [`dot-testing`](../SKILL.md) skill. A roadmap task runs `dot-testing` twice: in stub mode before `dot-implement`, and in fill mode after it. Use red-green TDD, where a test fails before the code exists, only when the user asks for it.
4
+
5
+ ## Stub mode
6
+
7
+ Run stub mode before the code exists.
8
+
9
+ 1. Read the "Test cases" section of the roadmap task.
10
+ 2. Write each case as a pending test (`it.todo`, `test.todo`, or the equivalent of the runner) in the test file of the module that the case covers. Use the order and the names that the cases give.
11
+ 3. Write no other test code: no `makeSut`, no doubles, and no assertions.
12
+
13
+ Done when each case is a pending test, and the test command reports them as pending.
14
+
15
+ ## Fill mode
16
+
17
+ Run fill mode after `dot-implement`. Read the "Test cases" section of the roadmap task, the diff of the task, and the handoff of `dot-implement`. The handoff has these fields:
18
+
19
+ ```markdown
20
+ **Expected failures:**
21
+ - `<test file>`: <test name>: <the new behavior that the test must assert>
22
+
23
+ **Behaviors that need tests:**
24
+ - `<module>`: <a behavior that the change adds or changes, and that no test case covers>
25
+ ```
26
+
27
+ 1. Turn each pending test of the task into a real test, by the rules in `SKILL.md`.
28
+ 2. Change each test in "Expected failures" so that it asserts the new behavior.
29
+ 3. Add a test for each item in "Behaviors that need tests", in the test file of its module.
30
+ 4. When a test fails because the production code is wrong, stop and report the failure. Do not change the production code.
31
+
32
+ Done when no pending test of the task remains, and the test command of the repository passes, with its output shown.
@@ -0,0 +1,3 @@
1
+ # Shared state
2
+
3
+ When the `sut` itself keeps mutable state between calls (an in-memory cache, a counter, a queue), a reset of the doubles leaves that state behind. Give that `describe` its own `makeSut` call before each test and `cleanup` after each test, and name that `describe` after the state, such as `describe("with a warm cache")`. Tests that run concurrently share the doubles the same way. So in a concurrent suite, each test calls `makeSut` itself and calls `cleanup` when it ends, and the suite has no shared restore hook: a global restore undoes the spies of tests that still run, and the doubles of each test end with that test.
@@ -10,7 +10,7 @@ TypeScript details for the [`dot-testing`](../SKILL.md) skill. Use the runner th
10
10
  | Release it | `afterAll` | `after` |
11
11
  | Restore the doubles | `afterEach(() => vi.restoreAllMocks())` or `jest.restoreAllMocks()` | `afterEach(() => mock.restoreAll())` |
12
12
 
13
- Write the doubles as plain objects with happy-path methods, not `jest.fn(impl)` or `vi.fn(impl)`: in Jest 29 and earlier, restoring or resetting mocks erases `impl`, which the next tests still need. Override a method per test with `vi.spyOn`, `jest.spyOn`, or `mock.method`, and restoring puts back the happy path.
13
+ Write the doubles as plain objects with happy-path methods, not `jest.fn(impl)` or `vi.fn(impl)`: in Jest 29 and earlier, a restore or a reset of the mocks erases `impl`, which the next tests still need. Override a method per test with `vi.spyOn`, `jest.spyOn`, or `mock.method`, and a restore puts back the happy path.
14
14
 
15
15
  ## Example
16
16
 
@@ -50,7 +50,7 @@ describe("UserService", () => {
50
50
  expect(name).toBe("Ada");
51
51
  });
52
52
 
53
- it("returns null when the user is missing", async () => {
53
+ it("returns null when the user does not exist", async () => {
54
54
  const { sut, repositoryStub } = suite;
55
55
  vi.spyOn(repositoryStub, "findById").mockResolvedValueOnce(null);
56
56
 
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: dot-writing-for-agents
3
+ description: Write documents for agents. Use when you create or edit skills, or change AGENTS.md or CLAUDE.md.
4
+ ---
5
+
6
+ Use this reference for any document that an agent reads: a skill, an `AGENTS.md` or `CLAUDE.md` file, or a doc that a pointer names. The package differs, but the method is the same. The same levers make each document predictable: the agent takes the same _process_ on every run, even when the output differs.
7
+
8
+ Read each reference that applies:
9
+
10
+ - [`references/pointers.md`](references/pointers.md): read when you write a skill description, an `AGENTS.md` line that names a doc, or another pointer, or when you decide whether to split a document.
11
+ - [`references/steps.md`](references/steps.md): read when the document has steps, for the completion criterion of each step.
12
+ - [`references/skill-mechanics.md`](references/skill-mechanics.md): read when the document is a skill, for the frontmatter, the invocation choice, and router skills.
13
+
14
+ ## Repository conventions first
15
+
16
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. When you edit the `AGENTS.md`, `CLAUDE.md`, or skills of a repository, keep their structure, format, and conventions.
17
+
18
+ ## Information hierarchy
19
+
20
+ A document has two types of content. **Steps** are the actions that the agent does, in order. **Reference** is the definitions, rules, and facts that the agent reads when it needs them. A document can have only steps (a recipe), only reference (the rules of a review, or this skill), or both. The main decision is where each part goes on the **information hierarchy**, a ladder ranked by how soon the agent needs the material:
21
+
22
+ 1. **In-file step**: the first tier. What the agent does, in order.
23
+ 2. **In-file reference**: material that the agent reads when it needs it. A flat set of peers, such as every rule of a review on one rung, is a correct arrangement.
24
+ 3. **Disclosed reference**: material in a separate file that a pointer names. The agent loads it only when the pointer fires. It can be a file next to the document, or an external file that any document can point to.
25
+
26
+ If you push too little down, the top gets too large. If you push too much down, you hide material that the agent needs. That trade-off is the whole decision.
27
+
28
+ **Progressive disclosure** moves material down the ladder, out of the main file and behind a pointer, so the top stays easy to read. It protects the hierarchy more than it saves tokens. Use branches to decide: put inline what every branch needs, and put behind a pointer what only some branches need. A **branch** is a distinct case that the document handles, so different runs take different paths through it. In a document with steps, reference that you should disclose buries the steps, and the agent attends to them only by chance.
29
+
30
+ **Co-location** decides what goes next to a part on the same rung. Keep the definition, rules, and caveats of a concept under one heading, so the agent reads them together. The document must read like documentation written for the agent. Scatter differs from duplication: duplication repeats one meaning in two places, and scatter splits one meaning across many places.
31
+
32
+ **Sprawl** is a document that is too long, even when every line is current and unique. Attention gets thin across the extra lines, and each line is one more to keep current. To fix sprawl, use the ladder: disclose reference behind pointers, and split by branch or by sequence so each path carries only what it needs.
33
+
34
+ ## Leading words
35
+
36
+ A **leading word** is a compact concept from the model's pretraining that the agent thinks with while it runs the document, such as _lesson_, _fog of war_, or _tracer bullets_. Repeat it as a token, never as a sentence. Each use adds to its definition, and it anchors a whole region of behavior in few tokens, because the model already holds its meaning. You can coin a word if you define it clearly, but a new word brings no prior meaning. You pay in definition tokens for what a known word gives for free, so try a known word first.
37
+
38
+ A leading word anchors in two places. In the body, it anchors _execution_: the agent does the same thing each time the word appears, and in flat reference it focuses attention on one class of thing to look for. In a pointer, it anchors _invocation_: when the same word is in your prompts, your docs, and your code, the agent links the shared word to the material and reaches it more reliably.
39
+
40
+ Look for text that a leading word can replace: a set of three adjectives at three sites, or a pointer that spends a sentence on one idea. Examples:
41
+
42
+ - "fast, deterministic, low-overhead" becomes _tight_, as in a _tight_ loop.
43
+ - "a loop you believe in" becomes _red_. The vague gate becomes a binary state: the loop goes _red_ on the bug, or it does not.
44
+
45
+ You get fewer tokens and a sharper hook for the agent. Assume that every document repeats ideas that a leading word can replace, and find them.
46
+
47
+ **Negation** is the failure mode next to this lever. A prohibition puts the forbidden behavior in context and makes it _more_ available. The negation is a weak modifier, and the strong concept overrides it, so the ban half reads as an instruction to do the thing. State the **positive** target instead, such as "write one-line comments", so the context never names the banned behavior. Use a prohibition only as a hard guardrail that you cannot state as a positive. Even then, pair it with the positive target.
48
+
49
+ ## Prune
50
+
51
+ - Keep each meaning in a **single source of truth**: one place, so a change to the behavior is a change in one place. **Duplication**, the same meaning in more than one place, costs maintenance and tokens. It also makes the meaning look more important than its real rung. A leading word repeats a token on purpose, never the meaning.
52
+ - The **environment** is also a source of truth: `package.json` scripts, configuration files, the directory layout, and `--help` output. A document that restates it is a **cache**: a copy of a lookup. A cache earns its load only when the lookup is expensive. Cache what the agent cannot find with a lookup: the unwritten convention, the reason for a choice, the gotcha that no configuration shows. Leave lookups of one file or one command to the environment, where they cannot go stale.
53
+ - Check every line for **relevance**: does it still apply to what the document does? A line loses relevance when it never applies to the task, such as an explanation or a branch that you should disclose. It also loses relevance when the behavior it describes changes. Short documents are easier to keep relevant. If you never prune, **sediment** collects: stale layers stay, because an addition feels safe and a removal feels risky.
54
+ - Find **no-ops**, one sentence at a time: an instruction that the model already obeys by default costs load and changes nothing. The test is "does it change the behavior from the default?", and it depends on the model, not the reader. When two people disagree about a no-op, they disagree about the default, so run the document to decide. When a sentence fails the test, delete the whole sentence. Do not trim words from it. The test also grades leading words: a word too weak to change the default, such as _be thorough_ when the agent is already thorough, is a no-op. The fix is a stronger word, such as _relentless_, not a different technique.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/productivity/writing-for-agents",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Added a 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md. Moved SKILL-MECHANICS.md to references/skill-mechanics.md, and moved the context pointers, the two loads, and the splits to references/pointers.md, and the completion criteria to references/steps.md."
8
+ }
@@ -0,0 +1,27 @@
1
+ # Pointers and splits
2
+
3
+ ## Context pointers
4
+
5
+ A **context pointer** is a reference in the agent's context that names material outside the context and states the condition to reach it. A skill's description is a pointer. A line in `AGENTS.md` that names a doc is the same object. The _wording_ of the pointer decides when the agent reaches the material, and how reliably. The target does not. A weak pointer to material that the agent must have is a variance bug. First make the wording sharper. Put the material inline only if that fails.
6
+
7
+ A pointer has two jobs: state what the material is, and list the **branches** that must trigger it. A branch is a distinct case that the material handles. Every word of an always-loaded pointer costs on every turn, so prune a pointer harder than the body:
8
+
9
+ - Put the **leading word** first. The pointer is where the word triggers the material.
10
+ - Write one trigger for each branch. Synonyms that name one branch are one branch written two times. Collapse them, and keep only the distinct branches.
11
+ - Cut identity that the body already carries.
12
+
13
+ ## The two loads
14
+
15
+ Every document and pointer that you add spends one of two budgets:
16
+
17
+ - **Context load** is the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything that is in context on every turn. It costs tokens and attention, whether or not it fires.
18
+ - **Cognitive load** is the cost on the person, who must know which documents exist and when to use each one. The person is the index. Do not minimize this cost: it is the price of human control. Spend it where human judgment matters, and remove it where it does not.
19
+
20
+ Material that only a pointer reaches costs no context load, except the line of the pointer. Material with no pointer costs only cognitive load.
21
+
22
+ ## When to split
23
+
24
+ A split of one document into two spends one of the two loads. Split only when the cut earns that cost:
25
+
26
+ - **By sequence**: split a run of steps when the steps after the end of the work tempt the agent to rush the current step. When the agent cannot see them, it does more legwork on the current task. The reverse also applies: a merge of two sequences shows each step the steps that follow it, and that causes premature completion.
27
+ - **By invocation**, for skills only: see [`skill-mechanics.md`](skill-mechanics.md).
@@ -0,0 +1,22 @@
1
+ # Skill mechanics
2
+
3
+ This is the branch of [`dot-writing-for-agents`](../SKILL.md) for skills: the frontmatter, the invocation choice, and router skills. Everything else about how to write a skill is in `SKILL.md` and [`pointers.md`](pointers.md).
4
+
5
+ ## Invocation
6
+
7
+ There are two choices, and each one trades one load for the other:
8
+
9
+ - A **model-invoked** skill keeps a `description`, so the agent can fire it on its own, and other skills can reach it. You can still type its name: model invocation always _includes_ the user's reach. A description only adds discovery by the agent, and never removes the person's reach. The description is the skill's top-level context pointer, and it stays loaded at all times: permanent context load in exchange for discovery. A model-invoked skill with only reference content is also one home for shared reference: another skill can invoke it, so several skills can use one copy of the reference. To set it up, omit `disable-model-invocation`, and write a description for the model that carries the trigger branches. The pointer rules in `pointers.md` apply in full.
10
+ - A **user-invoked** skill takes the description out of the agent's reach: only the person who types its name can invoke it, and no other skill can. It costs no context load, but it costs cognitive load: the person is the index that must remember that it exists. To set it up, set `disable-model-invocation: true`. The `description` is then for people: a one-line summary without trigger lists.
11
+
12
+ Pick model invocation only when the agent must reach the skill on its own, or another skill must reach it. If a person always fires it by hand, make it user-invoked and pay no context load.
13
+
14
+ Shared reference that two user-invoked skills both need cannot live in either one: with no descriptions, neither skill can fire the other. Put it in a plain file outside the skill system, as external reference that any skill can point to.
15
+
16
+ ## Split by invocation
17
+
18
+ This is the invocation cut of a split. The sequence cut is in `pointers.md`. Split off a model-invoked skill when it has a distinct leading word that must trigger it on its own, a word that you use in your prompts, or when another skill must reach it. The new description is always loaded and adds context load, so the separate reach must be worth that cost.
19
+
20
+ ## Router skills
21
+
22
+ When you have more user-invoked skills than you can remember, a **router skill** fixes that cognitive load. It is one user-invoked skill that names the others and when to use each one, so the person remembers one skill instead of many. It can only suggest the other skills and cannot fire them: user-invoked skills have no description, so only the person can reach them.
@@ -0,0 +1,8 @@
1
+ # Steps and completion criteria
2
+
3
+ End every step on a **completion criterion**, the condition that tells the agent the step is done. Two properties make it a lever:
4
+
5
+ - **Clarity**: the agent must tell done from not done. A vague bound, such as "understanding reached", causes **premature completion**: the agent ends the step before it is done, because its attention moves to the end. The steps still ahead, the **post-completion steps**, pull the agent forward, and a clear criterion holds it back. First, make the bound sharper, because that is local and cheap. Only if the bound stays vague _and_ you see the rush, hide the later steps: split the sequence. Hiding works only across a real context boundary, such as a handoff or a subagent. An inline call keeps the later steps in context.
6
+ - **Demand**: how much the criterion requires. "Every changed model accounted for" forces thorough work, and "produce a change list" does not. Demand drives **legwork**, the extra work that the wording implies but that no step states. Demand also binds reference: "every rule applied" binds a flat set of rules as "every step done" binds a sequence. So a document with only reference can still require full coverage.
7
+
8
+ The strongest criteria are checkable and exhaustive.
@@ -1,15 +0,0 @@
1
- # Code comments
2
-
3
- Apply these rules when you write, refactor, or review code:
4
-
5
- - Leave most code without comments. Comment the why the code can't show: a constraint, a workaround with its issue link, a non-obvious trade-off, an invariant, or the source of copied code. Keep it to one line when you can.
6
- - Let names and types carry the what. When a comment would restate the code, improve a name or extract a function instead.
7
- - Assume the reader knows the language, its libraries, and the platform. Comment only what is specific to this code.
8
- - Write comments for future readers of the code as it is. Change history, notes such as "added" or "now uses", and messages to the reviewer belong in the commit message or pull request.
9
- - Delete code instead of commenting it out. Git keeps the history.
10
- - Write doc comments where the repository documents its APIs, or on an exported API whose name and types don't show its contract. Cover purpose, contract, errors, and side effects, not the implementation.
11
- - Write comments above a function, class, property, or other declaration as doc comments in the language's convention, such as `/** */` JSDoc in TypeScript, so editors show them in hover tooltips, unless the surrounding code uses another style.
12
- - Explain regular expressions and complex algorithms with what they match or compute.
13
- - When you change code, update every comment that the change makes inaccurate, and delete comments that no longer apply.
14
- - When you review code, flag comments that restate the code, contradict it, or narrate changes, and ask for a why comment where intentional code looks wrong.
15
- - Match the comment density and style of the surrounding code. In a new file, match the repository's other files.
@@ -1,58 +0,0 @@
1
- ---
2
- name: dot-code-review
3
- description: Review a diff for correctness bugs. Use when the user asks to review code, a commit, a branch, or a pull request, or before committing a non-trivial change.
4
- ---
5
-
6
- # Code review
7
-
8
- Find the defects that would make this change behave wrongly in production. Each finding is a **failure scenario**: concrete inputs or state that lead to a wrong result, a crash, or data loss.
9
-
10
- ## Repository conventions first
11
-
12
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Review against those standards. Code that follows a repository convention isn't a finding, even when general practice differs; code that breaks one is.
13
-
14
- ## 1. Pick the target
15
-
16
- Use the target the user named. Otherwise pick the first one that applies:
17
-
18
- 1. A pull request number or URL: `gh pr diff <number>`.
19
- 2. Staged and unstaged changes: `git diff HEAD`.
20
- 3. The current branch against its base: `git diff $(git merge-base HEAD origin/main)`. Use the repository's default branch name.
21
-
22
- State the target in one line before you start.
23
-
24
- ## 2. Read for context
25
-
26
- For each changed hunk, read the whole function, its callers, and the tests that cover it. Read the description of the pull request or linked issue if there is one, so you can check the change against its intent.
27
-
28
- ## 3. Hunt
29
-
30
- Check every hunk against each of these classes:
31
-
32
- - **Logic**: inverted conditions, off-by-one errors, wrong operator, wrong variable, unreachable branches.
33
- - **Edge cases**: empty, null, zero, negative, very large, Unicode, duplicate, and concurrent inputs.
34
- - **Errors**: swallowed exceptions, missing cleanup, partial writes, retries that aren't idempotent.
35
- - **Contracts**: changed signatures, return shapes, defaults, or API responses that existing callers depend on.
36
- - **Data**: migrations that lose or lock data, missing transactions, inconsistent writes.
37
- - **Security**: injection, missing authorization checks, secrets in code or logs, unsafe deserialization, path traversal.
38
- - **Concurrency**: races, deadlocks, shared mutable state, ordering assumptions.
39
- - **Tests**: changed behavior without a test that would fail if the change were wrong.
40
-
41
- ## 4. Verify each finding
42
-
43
- For each candidate, prove it: trace the code path with the failing input, or write and run a test that fails. Drop candidates you can't support with a concrete scenario, or report them as questions.
44
-
45
- Report style issues only when they hide a bug or break a documented project convention.
46
-
47
- ## 5. Report
48
-
49
- List findings from most to least severe:
50
-
51
- ```markdown
52
- ### <severity: high | medium | low> <one-line summary>
53
- `path/to/file.ts:42`
54
- **Scenario:** <inputs or state> → <wrong result>
55
- **Fix:** <smallest change that removes the defect>
56
- ```
57
-
58
- If you find nothing, say that the review found no defects, and list what you checked. Change code only when the user asks for fixes.
@@ -1,142 +0,0 @@
1
- ---
2
- name: dot-debug
3
- description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
4
- ---
5
-
6
- # Diagnosing Bugs
7
-
8
- A discipline for hard bugs. Skip phases only when explicitly justified.
9
-
10
- When exploring the codebase, read `GLOSSARY.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
11
-
12
- ## Repository conventions first
13
-
14
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Build the feedback loop with the repository's own test framework, scripts, and tooling.
15
-
16
- ## Redact
17
-
18
- This skill has you show commands, outputs and captured artifacts. **Redact every secret first**: write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
19
-
20
- If the redacted output is not enough to diagnose the bug, say so and ask the user.
21
-
22
- ## Phase 1: Build a feedback loop
23
-
24
- **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug (one that goes red on _this_ bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
25
-
26
- Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
27
-
28
- ### Ways to construct one, in roughly this order
29
-
30
- 1. **Failing test** at whatever seam reaches the bug: unit, integration, e2e.
31
- 2. **Curl / HTTP script** against a running dev server.
32
- 3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
33
- 4. **Headless browser script** (Playwright / Puppeteer) that drives the UI and asserts on DOM/console/network.
34
- 5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
35
- 6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
36
- 7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
37
- 8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
38
- 9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
39
- 10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
40
-
41
- Build the right feedback loop, and the bug is 90% fixed.
42
-
43
- ### Tighten the loop
44
-
45
- Treat the loop as a product. Once you have _a_ loop, **tighten** it:
46
-
47
- - Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
48
- - Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
49
- - Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
50
-
51
- A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight, a debugging superpower.
52
-
53
- ### Non-deterministic bugs
54
-
55
- The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not, so keep raising the rate until it's debuggable.
56
-
57
- ### When you genuinely cannot build a loop
58
-
59
- Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
60
-
61
- ### Completion criterion: a tight loop that goes red
62
-
63
- Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** (a script path, a test invocation, a curl) that you have **already run at least once** (show the invocation and its output, redacted), and that is:
64
-
65
- - [ ] **Red-capable**: it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring"; it must be able to _catch this specific bug_.
66
- - [ ] **Deterministic**: same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
67
- - [ ] **Fast**: seconds, not minutes.
68
- - [ ] **Agent-runnable**: you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
69
-
70
- If you catch yourself reading code to build a theory before this command exists, **stop: jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
71
-
72
- ## Phase 2: Reproduce + minimise
73
-
74
- Run the loop. Watch it go red as the bug appears.
75
-
76
- Confirm:
77
-
78
- - [ ] The loop produces the failure mode the **user** described, not a different failure that happens to be nearby. Wrong bug = wrong fix.
79
- - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
80
- - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
81
-
82
- ### Minimise
83
-
84
- Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut, and keep only what's load-bearing for the failure.
85
-
86
- Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
87
-
88
- Done when **every remaining element is load-bearing**: removing any one of them makes the loop go green.
89
-
90
- Do not proceed until you have reproduced **and** minimised.
91
-
92
- ## Phase 3: Hypothesise
93
-
94
- Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
95
-
96
- Each hypothesis must be **falsifiable**: state the prediction it makes.
97
-
98
- > Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
99
-
100
- If you cannot state the prediction, the hypothesis is a vibe: discard or sharpen it.
101
-
102
- **Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it; proceed with your ranking if the user is AFK.
103
-
104
- ## Phase 4: Instrument
105
-
106
- Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
107
-
108
- Tool preference:
109
-
110
- 1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
111
- 2. **Targeted logs** at the boundaries that distinguish hypotheses.
112
- 3. Never "log everything and grep".
113
-
114
- **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
115
-
116
- **Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
117
-
118
- ## Phase 5: Fix + regression test
119
-
120
- Write the regression test **before the fix**, but only if there is a **correct seam** for it.
121
-
122
- A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
123
-
124
- **If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
125
-
126
- If a correct seam exists:
127
-
128
- 1. Turn the minimised repro into a failing test at that seam.
129
- 2. Watch it fail. If you forced the red by mutating code or a fixture, `diff` against a pristine copy to prove the mutation landed before you trust it.
130
- 3. Apply the fix.
131
- 4. Watch it pass.
132
- 5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
133
-
134
- ## Phase 6: Cleanup
135
-
136
- Required before declaring done:
137
-
138
- - [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
139
- - [ ] Regression test passes (or absence of seam is documented)
140
- - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
141
- - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
142
- - [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns
@@ -1,8 +0,0 @@
1
- {
2
- "repository": "https://github.com/mattpocock/skills",
3
- "path": "skills/engineering/diagnosing-bugs",
4
- "commit": "49dd158d1076134a641b33efb035946536778336",
5
- "license": "MIT",
6
- "modified": true,
7
- "notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a 'Repository conventions first' section. Renamed with the dot- prefix."
8
- }
@@ -1,34 +0,0 @@
1
- ---
2
- name: dot-grilling
3
- description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
4
- ---
5
-
6
- Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
7
-
8
- Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
9
-
10
- Format a round like so:
11
-
12
- ```
13
- ❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
14
-
15
- ➡️ <your recommended answer>
16
-
17
- ---
18
-
19
- ❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
20
-
21
- ➡️ <your recommended answer>
22
- ```
23
-
24
- Word each question so "yes" accepts your recommended answer.
25
-
26
- Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
27
-
28
- Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
29
-
30
- The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.
31
-
32
- ## Repository conventions first
33
-
34
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Ground your recommended answers in those conventions.
@@ -1,3 +0,0 @@
1
- interface:
2
- display_name: "Grilling"
3
- short_description: "Stress-test thinking a round of questions at a time"
@@ -1,20 +0,0 @@
1
- ---
2
- name: dot-handoff
3
- description: Compact the current conversation into a handoff document for another agent to pick up.
4
- argument-hint: "What will the next session be used for?"
5
- disable-model-invocation: true
6
- ---
7
-
8
- Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS (`$TMPDIR`, else `/tmp`; `%TEMP%` on Windows) - not the current workspace.
9
-
10
- Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.
11
-
12
- Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
13
-
14
- Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
15
-
16
- If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
17
-
18
- ## Repository conventions first
19
-
20
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. List the repository conventions that the next agent must follow, by path.
@@ -1,52 +0,0 @@
1
- ---
2
- name: dot-implement
3
- description: Implement a feature, fix, refactor, or roadmap task to the repository's and the language's standards. Use when the user asks to build or change code, or to work a task from a dot-roadmap roadmap.
4
- ---
5
-
6
- # Implement
7
-
8
- Turn a request, an approved plan, or a roadmap task into a working change that ends **green**: every check the work names passes, and you've shown the output.
9
-
10
- ## Repository conventions first
11
-
12
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Write code that fits those conventions.
13
-
14
- ## 1. Pin the work
15
-
16
- Identify the source of the work:
17
-
18
- - **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's decisions in full. The task's "Out of scope" is a hard boundary.
19
- - **Approved plan**: the plan in this conversation, from `dot-plan` or the user.
20
- - **Request**: anything else.
21
-
22
- Done when you can state the goal, the scope boundary, and the check that proves the work is done.
23
-
24
- ## 2. Plan when needed
25
-
26
- A roadmap task or an approved plan is already the plan. For a request that touches more than one file, use the `dot-plan` skill and wait for the user's approval before you change any file. A single-file change goes straight to step 3.
27
-
28
- ## 3. Build
29
-
30
- For each language the change touches, read its reference if one exists:
31
-
32
- - [`references/typescript.md`](references/typescript.md): TypeScript and TSX.
33
-
34
- When you write or change tests, use the `dot-testing` skill.
35
-
36
- Work through the plan one step at a time, and run each step's check before you start the next one.
37
-
38
- Done when every requirement of the task, plan, or request has code that meets it.
39
-
40
- ## 4. Verify
41
-
42
- Run the task's "Verify" section, the plan's final check, or the repository's tests, type checker, and linter, and show the output. Check every acceptance criterion one by one. Reread your diff against the code comments rule, and fix what it flags.
43
-
44
- When verification fails, or the task or plan turns out wrong (a fact contradicts it, or meeting it needs work outside its scope), stop. Report the failing check or the conflicting fact and propose a change to the task or plan. Keep the task file, the roadmap's decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
45
-
46
- For a roadmap task, tick its checkbox in the roadmap's `README.md` once everything passes.
47
-
48
- Done when the work is green.
49
-
50
- ## 5. Hand off
51
-
52
- End with the verification output and anything you skipped or couldn't check. Suggest the `dot-code-review` skill for the diff, then the `dot-commit` skill. Leave the commit to the user.
@@ -1,44 +0,0 @@
1
- ---
2
- name: dot-testing
3
- description: Write and change tests with a makeSut factory per suite. Use when adding, fixing, or restructuring tests, unit or integration.
4
- ---
5
-
6
- # Testing
7
-
8
- Write tests that build the **system under test** (`sut`) in one factory, share it across the suite, and stay isolated by resetting the test doubles between tests.
9
-
10
- ## Repository conventions first
11
-
12
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. When the repository already sets up tests another way, such as pytest fixtures or its own setup helper, use that and leave out `makeSut`.
13
-
14
- ## The makeSut factory
15
-
16
- Use `makeSut` when the subject needs setup: construction, configuration, dependencies, or a resource such as a database or a server. Call a subject without setup directly in its own `describe`: pure functions, utilities, and constants. The test is "does it need setup?", not "is it a utility?"; a utility that takes an injected clock gets a `makeSut`.
17
-
18
- - Name it in the language's casing (`makeSut`, `make_sut`), and always call the tested object `sut`.
19
- - Give it no parameters. It returns an object with `sut`, every test double by name, and `cleanup` when a resource needs releasing: `{ sut, repositoryStub, cleanup }`. When setup fails partway, it releases what it already opened before rethrowing.
20
- - Build each test double in its own factory (`makeRepositoryStub()`) whose methods return the happy path, so a test spells out only what differs.
21
- - Place `makeSut` and the double factories in the test file, after the imports. Move them to a shared helper once a second test file needs them.
22
-
23
- ## Suite lifecycle
24
-
25
- 1. Call `makeSut` once per top-level `describe`, in the hook that runs before all tests, and call `cleanup` in the hook that runs after all of them.
26
- 2. In a test, change a dependency's behavior by spying on or stubbing the double that `makeSut` returned, for that test only.
27
- 3. Restore every spy and stub in the hook that runs after each test, so the next test sees the happy-path doubles again.
28
-
29
- When the `sut` itself keeps mutable state between calls (an in-memory cache, a counter, a queue), resetting the doubles leaves that state behind. Give that `describe` its own `makeSut` call before each test and `cleanup` after each test, with a comment that names the state. Tests that run concurrently share the doubles the same way, so in a concurrent suite each test calls `makeSut` itself, calls `cleanup` when it ends, and drops the shared restore hook: a global restore undoes the spies of tests still running, and each test's doubles die with it.
30
-
31
- ## Test principles
32
-
33
- - Arrange, act, assert: one block each, in that order.
34
- - Test one behavior per test, and name the test after that behavior ("returns null when the user is missing").
35
- - Assert on outputs and on calls that cross the `sut`'s boundary, not on its private steps.
36
- - Prefer stubs and fakes that return data to mocks that assert the call sequence.
37
-
38
- ## Language references
39
-
40
- Read the reference for each language the tests use, if one exists:
41
-
42
- - [`references/typescript.md`](references/typescript.md): TypeScript with Vitest, Jest, or `node:test`.
43
-
44
- Done when every test you wrote or changed passes with the repository's test command, and you've shown the output.
@@ -1,22 +0,0 @@
1
- # Skill mechanics
2
-
3
- The skill-specific branch of [`dot-writing-for-agents`](SKILL.md): what changes when the document is a skill (frontmatter, the invocation choice, and router skills). Everything else about writing it is the universal reference in `SKILL.md`.
4
-
5
- ## Invocation
6
-
7
- Two choices, trading the two loads:
8
-
9
- - A **model-invoked** skill keeps a `description`, so the agent can fire it autonomously, and other skills can reach it. You can still type its name: model-invocation always _includes_ user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times: permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omit `disable-model-invocation`, and write a model-facing description carrying the trigger branches (the pointer-writing rules in `SKILL.md` apply in full).
10
- - A **user-invoked** skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load: you are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing: a one-line summary, trigger lists stripped.
11
-
12
- Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
13
-
14
- Shared reference that two user-invoked skills both need can live in neither: with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
15
-
16
- ## Splitting by invocation
17
-
18
- The invocation cut of splitting (the sequence cut lives in `SKILL.md`): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own (a trigger word you actually use in your prompts), or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
19
-
20
- ## Router skills
21
-
22
- When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.