@igorlau/dotagents 0.0.0-stage → 1.0.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 (43) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +71 -2
  3. package/THIRD_PARTY_NOTICES.md +73 -0
  4. package/content/rules/comments.md +13 -0
  5. package/content/rules/core.md +8 -0
  6. package/content/rules/ponytail.md +29 -0
  7. package/content/rules/ponytail.upstream.json +8 -0
  8. package/content/skills/code-review/SKILL.md +58 -0
  9. package/content/skills/commit/SKILL.md +77 -0
  10. package/content/skills/debug/SKILL.md +142 -0
  11. package/content/skills/debug/UPSTREAM.json +8 -0
  12. package/content/skills/debug/agents/openai.yaml +3 -0
  13. package/content/skills/debug/scripts/hitl-loop.template.sh +44 -0
  14. package/content/skills/docs-writing/SKILL.md +82 -0
  15. package/content/skills/docs-writing/references/formatting.md +150 -0
  16. package/content/skills/docs-writing/references/global-and-accessible.md +46 -0
  17. package/content/skills/docs-writing/references/word-list.md +112 -0
  18. package/content/skills/grill-me/SKILL.md +11 -0
  19. package/content/skills/grill-me/UPSTREAM.json +8 -0
  20. package/content/skills/grill-me/agents/openai.yaml +5 -0
  21. package/content/skills/grilling/SKILL.md +34 -0
  22. package/content/skills/grilling/UPSTREAM.json +8 -0
  23. package/content/skills/grilling/agents/openai.yaml +3 -0
  24. package/content/skills/handoff/SKILL.md +20 -0
  25. package/content/skills/handoff/UPSTREAM.json +8 -0
  26. package/content/skills/handoff/agents/openai.yaml +5 -0
  27. package/content/skills/plan/SKILL.md +58 -0
  28. package/content/skills/writing-for-agents/SKILL-MECHANICS.md +22 -0
  29. package/content/skills/writing-for-agents/SKILL.md +85 -0
  30. package/content/skills/writing-for-agents/UPSTREAM.json +8 -0
  31. package/content/skills/writing-for-agents/agents/openai.yaml +3 -0
  32. package/dist/apply.js +119 -0
  33. package/dist/blocks.js +28 -0
  34. package/dist/build-info.json +1 -0
  35. package/dist/catalog.js +50 -0
  36. package/dist/cli.js +80 -0
  37. package/dist/commands.js +181 -0
  38. package/dist/frontmatter.js +23 -0
  39. package/dist/git.js +7 -0
  40. package/dist/manifest.js +35 -0
  41. package/dist/paths.js +25 -0
  42. package/dist/targets.js +74 -0
  43. package/package.json +36 -4
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: docs-writing
3
+ description: Write and edit developer documentation in the Google developer documentation style. Use when creating or revising a README, guide, tutorial, reference page, changelog, or code comments meant for readers.
4
+ ---
5
+
6
+ # Docs writing
7
+
8
+ Write documentation that a developer in a hurry, reading in their second language, can follow on the first pass. The rules come from the Google developer documentation style guide.
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. This includes the project's documentation style guide, prose linter configuration such as Vale, and the structure and terms of its existing docs.
13
+
14
+ ## 1. Frame the document
15
+
16
+ Before drafting, answer these questions:
17
+
18
+ - **Reader**: who is "you" in this document (an app developer, an operator, a contributor), and what do they already know?
19
+ - **Goal**: what can the reader do after reading?
20
+ - **Type**: a task (how to do something), a concept (how something works), or reference (facts to look up). Use a task title with a bare verb, such as "Deploy the service", and a concept title with a noun phrase, such as "Deployment model".
21
+
22
+ ## 2. Draft with the core rules
23
+
24
+ **Voice and tone**
25
+
26
+ - Write like a knowledgeable colleague: conversational and direct, without slang, jokes, or hype.
27
+ - Address the reader as "you". Use the imperative for instructions. Use "we" only for a named organization.
28
+ - Use active voice and name the actor: "The server sends a response", not "A response is sent".
29
+ - Use present tense. Use "will" only for events that happen later.
30
+ - Use common contractions, such as "don't" and "isn't".
31
+ - Write "click **Save**", not "please click" or "simply click". Words such as "simply", "easy", "just", and "quickly" judge difficulty for the reader, so leave them out.
32
+
33
+ **Sentences**
34
+
35
+ - Keep sentences under 26 words, with the subject and verb near the start.
36
+ - Put the condition before the instruction: "If the build fails, run `make clean`."
37
+ - Put the goal before the action: "To create a folder, click **New**."
38
+ - Use the same term for the same concept throughout. Spell out an abbreviation at its first use.
39
+ - Replace ambiguous pronouns ("it", "this") with the noun.
40
+ - Use "can" for ability, "might" for possibility, and "must" for requirements. Avoid "should" and "may".
41
+
42
+ **Structure**
43
+
44
+ - Use sentence case for titles and headings. Don't skip heading levels, and use one level-1 heading per page.
45
+ - Introduce every list, table, code sample, and procedure with a complete sentence that ends in a colon.
46
+ - Use numbered lists for sequences and bulleted lists for everything else. Keep list items parallel.
47
+ - Write each procedure step as one imperative action. State where the action happens before the action.
48
+ - Use serial commas: "Linux, macOS, and Windows".
49
+
50
+ **Formatting**
51
+
52
+ - Put code-related text in code font: commands, filenames, paths, variables, values, and field input.
53
+ - Put UI element names in bold, matching the label's capitalization: click **Create project**.
54
+ - Write placeholders in uppercase with underscores, such as `PROJECT_ID`, and explain each one after the sample.
55
+ - Use descriptive link text, such as the page title. Never use "click here" or a bare URL.
56
+ - Write dates as "January 19, 2026", or as ISO 8601 (`2026-01-19`) when space is tight.
57
+ - Give every image alt text, and never put information only in an image.
58
+
59
+ ## 3. Revise
60
+
61
+ Read the draft once per checklist item, and fix every instance:
62
+
63
+ - [ ] Each heading matches its section type (task, concept, or reference).
64
+ - [ ] No passive voice hides who acts.
65
+ - [ ] No sentence exceeds 26 words.
66
+ - [ ] Every list, table, and code block has an introductory sentence.
67
+ - [ ] Every placeholder is explained.
68
+ - [ ] Every command and code sample runs as written, apart from its placeholders.
69
+ - [ ] No directional language ("above", "below", "on the right"). Use "preceding", "following", or the element's name.
70
+ - [ ] No words from the word list's "avoid" entries.
71
+
72
+ ## References
73
+
74
+ Load the reference that matches what you're writing:
75
+
76
+ - [`references/formatting.md`](references/formatting.md): headings, lists, tables, procedures, code samples, commands, placeholders, notices, links, UI elements, and dates in detail.
77
+ - [`references/word-list.md`](references/word-list.md): words and phrases to avoid, with replacements. Read it during the revision pass.
78
+ - [`references/global-and-accessible.md`](references/global-and-accessible.md): writing for a global audience, accessibility, and inclusive language.
79
+
80
+ ---
81
+
82
+ Adapted from the [Google developer documentation style guide](https://developers.google.com/style), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Condensed and reorganized for use by coding agents.
@@ -0,0 +1,150 @@
1
+ # Formatting reference
2
+
3
+ Detailed formatting rules for the [`docs-writing`](../SKILL.md) skill.
4
+
5
+ ## Headings and titles
6
+
7
+ - Use sentence case: "Transfer data sets", not "Transfer Data Sets".
8
+ - Start task headings with a bare verb: "Create an instance", not "Creating an instance".
9
+ - Write concept headings as noun phrases that don't start with an -ing verb: "Migration to the cloud".
10
+ - Gerunds are acceptable only when no better option exists, such as "Billing".
11
+ - Prefix optional sections with "Optional:", as in "Optional: Customize your alias".
12
+ - Use exactly one level-1 heading per page, and make it unique in the doc set. Don't repeat the page title as a section heading.
13
+ - Don't skip levels: a level-3 heading belongs under a level-2 heading.
14
+ - Follow every heading with content.
15
+ - Don't number headings to show sequence, and don't put links in headings.
16
+ - Avoid code in headings. If you must, add a descriptive noun, such as "The `init` command".
17
+ - Keep heading punctuation minimal. Heavy punctuation means the heading needs rewriting.
18
+ - Introduce a group of subsections with "the following sections", not "this section" or "these sections".
19
+
20
+ ## Lists
21
+
22
+ - Use a numbered list when order matters, a bulleted list when it doesn't, and a description list for term-definition pairs.
23
+ - Don't make a list of one item.
24
+ - Introduce a list with a complete sentence. End the sentence with a colon if the list follows immediately, or with a period if other material comes between them.
25
+ - Recommended: "Use the **Submit** button for any of the following purposes:"
26
+ - Not recommended: "Use the **Submit** button to:"
27
+ - Make items parallel in syntax and structure.
28
+ - Start each item with a capital letter.
29
+ - End items with a period unless the item is a single word, has no verb, is entirely code, or is entirely link text. When items are mixed, make them parallel or punctuate all of them.
30
+ - In run-in lists, separate the bold term from its description with a colon or a period, and use the same punctuation for every item.
31
+ - In prose lists, don't end with "etc." or "and so on". Introduce the list so that it's clearly not exhaustive, for example with "including".
32
+ - Nest sequential sub-items with lowercase letters, and their sub-items with lowercase Roman numerals.
33
+
34
+ ## Tables
35
+
36
+ - Use a table when each item has three or more related pieces of data. A one-column table should be a list.
37
+ - Introduce each table with a complete sentence that states its purpose.
38
+ - Use sentence case for column headings, without ending punctuation.
39
+ - Don't merge cells, and don't put a table in the middle of a numbered procedure.
40
+ - Sort rows logically, or alphabetically when no logical order exists.
41
+ - Refer to a table by its position, such as "the following table", not "the table below".
42
+
43
+ ## Procedures
44
+
45
+ - Use a numbered list for two or more steps. Write a one-step procedure as a single bulleted sentence.
46
+ - Introduce the procedure with a complete sentence: "To rename the folder, follow these steps:". Skip the introduction only if the heading says everything.
47
+ - Start each step with an imperative verb, and use one action per step. Combine sequential menu selections with `>`: "Click **File > Save as**".
48
+ - State the location before the action: "In the admin console, go to **Users**."
49
+ - State the goal before the action: "To create a folder, click **New**." If the goal makes the step look optional, put the action first: "Sort the data by date: click **Sort**."
50
+ - Begin optional steps with "Optional:".
51
+ - Give the result after the action, in the same step: "Click **Submit**. A confirmation message appears."
52
+ - State the action, then its reason: "Store the token safely. You need it to sign in later."
53
+ - Order a complex step as follows: action, command, placeholder explanations, further explanation, output, result.
54
+ - List prerequisites (hardware, software, permissions, information) before the first step.
55
+ - When two procedures share steps, link to the earlier one instead of repeating it.
56
+ - Document one method, the shortest one that works for every reader. Separate alternatives with headings or tabs only when necessary.
57
+
58
+ ## Code in text
59
+
60
+ Use code font for the following items:
61
+
62
+ - Commands, utilities, flags, and options: `kubectl`, `--force`.
63
+ - Filenames, paths, directories, and extensions.
64
+ - Class, method, function, variable, enum, and constant names.
65
+ - Data types, keywords, attribute names and values, and environment variables.
66
+ - HTTP verbs and status codes, such as `POST` and `404 Not Found`, and content types.
67
+ - Port numbers, query parameters, and package names.
68
+ - Text that the reader types and command output.
69
+ - Placeholders.
70
+
71
+ Don't use code font for product names, domain names in prose, or URLs that the reader visits in a browser.
72
+
73
+ Use code names grammatically as proper nouns. Don't pluralize them, make them possessive, or turn them into verbs. Add a plain noun instead:
74
+
75
+ - Recommended: "The `ADDRESS` constant's value", "send a `POST` request".
76
+ - Not recommended: "`ADDRESS`'s value", "`POST` the data".
77
+
78
+ Don't wrap code in quotation marks unless the quotation marks are part of the code.
79
+
80
+ ## Code samples
81
+
82
+ - Introduce each sample with a sentence that ends in a colon.
83
+ - Use fenced code blocks with a language tag.
84
+ - Wrap lines at 80 characters.
85
+ - Mark omitted code with a comment in the sample's language. Don't use an ellipsis.
86
+ - Follow the language's own style guide, or the project's.
87
+
88
+ ## Commands
89
+
90
+ - Make copyable commands runnable as written, apart from placeholders.
91
+ - Link each command to its reference documentation where it's introduced.
92
+ - Show as few optional flags as possible. Point to the reference for the rest.
93
+ - Break long commands before a flag, end each continued line with ` \` (or ` ^` on Windows), and indent continuation lines four spaces.
94
+ - In multi-line examples, start each input line with `$`. If a document mixes one-line and multi-line commands, use the prompt for all of them. Don't show the current directory.
95
+ - Put input and output in separate code blocks.
96
+ - Show output only when the reader needs to verify or copy a value. Introduce it with "The output is similar to the following:". Mark omitted lines with `...` on a line of its own.
97
+ - In syntax descriptions, wrap optional arguments in `[]`, mutually exclusive choices in `{a|b}`, and mark repeatable arguments with `...`. Keep these symbols out of copyable commands.
98
+
99
+ ## Placeholders
100
+
101
+ - Use descriptive uppercase names with underscores: `PROJECT_ID`, not `x`, `my-project`, or `YOUR_PROJECT`.
102
+ - In Markdown prose, write placeholders as code.
103
+ - Explain every placeholder after its first appearance, even if it seems obvious:
104
+ - For one placeholder: "Replace `PROJECT_ID` with the ID of your project."
105
+ - For several placeholders: "Replace the following:", then a list in the order they appear, each item as "`NAME`: description that starts with a lowercase letter".
106
+ - Explain placeholders in output with "This output includes the following values:".
107
+
108
+ ## Notices
109
+
110
+ - Use notices sparingly, and never place two in a row.
111
+ - **Note:** relevant but optional information that the reader can skip.
112
+ - **Caution:** proceed carefully.
113
+ - **Warning:** an action might cause irreversible harm, such as data loss, cost, or a security exposure.
114
+ - Don't use a notice for prerequisites, required steps, results, or cross-references. Put that information in the main text.
115
+ - Start each notice with its bold label and a colon: "**Note:**".
116
+
117
+ ## Links
118
+
119
+ - Use the destination's page title, or a short descriptive phrase with the key words first, as link text.
120
+ - Never use "click here", "this page", "this document", or a bare URL as link text.
121
+ - Introduce cross-references with "For more information, see LINK." or "For more information about TOPIC, see LINK."
122
+ - Link only what's relevant, and don't repeat a link to the same destination on one page.
123
+ - Say when a link downloads a file or leaves the doc set. Don't force new tabs.
124
+ - Keep punctuation outside the link text, and don't put link text in quotation marks.
125
+
126
+ ## UI elements
127
+
128
+ - Put UI element names in bold, matching their capitalization on screen. Use sentence case if the label is all caps.
129
+ - Name the element and its type: "the **Name** field", "the **File** menu", "the **Advanced** tab".
130
+ - Use "click" for buttons and links, "select" and "clear" for checkboxes and options, "enter" for text, and "press" for keys. Don't write "click on", "hit", "check", or "uncheck".
131
+ - Use "in" with dialogs, fields, lists, menus, panes, and windows, and "on" with pages, tabs, and toolbars.
132
+ - Don't use a UI label as a verb: "To save the file, click **Save**", not "**Save** the file".
133
+ - Write key combinations with spelled-out modifier names: Control+S. For several operating systems, give Windows and Linux first and macOS in parentheses.
134
+
135
+ ## Dates and times
136
+
137
+ - Write dates with the full month and a four-digit year: "January 19, 2026". Abbreviate only in tables or headings: "Jan 19, 2026".
138
+ - When a numeric date is unavoidable, use ISO 8601: `2026-01-19`.
139
+ - Use the 12-hour clock with AM or PM: "3:45 PM", "3 PM". Use 24-hour time only when the product uses it.
140
+ - Avoid time zones unless they're necessary. Spell out the region and add the UTC offset: "Pacific Standard Time (UTC-8)".
141
+ - Avoid seasons, because they differ between hemispheres. Use months or quarters.
142
+
143
+ ## Numbers
144
+
145
+ - Use numerals for numbers that are followed by a unit, and in technical contexts.
146
+ - Write "10 times", not "10x".
147
+
148
+ ---
149
+
150
+ Adapted from the [Google developer documentation style guide](https://developers.google.com/style), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
@@ -0,0 +1,46 @@
1
+ # Global and accessible writing
2
+
3
+ Rules for the [`docs-writing`](../SKILL.md) skill that help readers who use translation tools, read in a second language, or use assistive technology.
4
+
5
+ ## Global audience
6
+
7
+ - Use simple words: "start", not "commence"; "so", not "consequently"; "some" or "many", not "a number of".
8
+ - Prefer one-word verbs to phrasal verbs, except standard terms such as "set up" and "sign in".
9
+ - Use each word in its primary sense, and don't use the same word as a noun and a verb close together.
10
+ - Use subject-verb-object order, and keep the subject and verb near the start of the sentence.
11
+ - Keep helper words that make structure explicit: "that", "then", "of". Write "Update the rules that you defined", not "Update the rules you defined".
12
+ - Write "if X, then Y" in technical conditions.
13
+ - Place "only" directly before the word it modifies.
14
+ - Use no more than two nouns to modify another noun.
15
+ - Replace "using" with "by using" or "that uses" when the meaning is unclear.
16
+ - Avoid idioms, metaphors, humor, slang, pop culture, sports references, and holidays.
17
+ - Use a diverse set of names in examples, and use example domains such as `example.com`.
18
+ - Address the reader as "you". Use "users" only for the people who use the software that the reader builds.
19
+ - State what the reader can do instead of what they can't.
20
+
21
+ ## Accessibility
22
+
23
+ - Break text into short paragraphs, headings, and lists. Put the key information in the first sentence of each paragraph.
24
+ - Keep sentences under 26 words. Avoid double negatives and exceptions to exceptions.
25
+ - Define acronyms at first use, and again if they appear rarely.
26
+ - Write link text that makes sense out of context, because screen reader users often navigate by links alone.
27
+ - Give every image alt text that conveys its purpose. Use empty alt text for decorative images.
28
+ - Never put information only in an image, and never use images of text, code, or terminal output.
29
+ - Don't rely on color, size, position, or shape alone. Pair each with a text label.
30
+ - Refer to UI elements by their labels, not by appearance ("the bell icon") or position ("on the right").
31
+ - Use "and", not "&", except in UI labels and code.
32
+ - Don't rely on punctuation alone to carry meaning, because some screen readers skip it.
33
+ - Don't insert hard line breaks inside sentences.
34
+ - Introduce every table, and use header cells for the first row or column only.
35
+ - Provide captions or transcripts for audio and video, and avoid flashing content.
36
+
37
+ ## Inclusive language
38
+
39
+ - Use gender-neutral language. Use "they" for a person of unknown gender.
40
+ - Use people-first or identity-first language as each community prefers. Don't describe people without disabilities as "normal" or "healthy".
41
+ - Replace terms with violent, ableist, or oppressive connotations. See the inclusive language table in [`word-list.md`](word-list.md).
42
+ - When code requires a non-inclusive term, use it only in code font, and use the inclusive term in prose.
43
+
44
+ ---
45
+
46
+ Adapted from the [Google developer documentation style guide](https://developers.google.com/style), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
@@ -0,0 +1,112 @@
1
+ # Word list
2
+
3
+ Words and phrases for the [`docs-writing`](../SKILL.md) skill. Each entry lists the word to replace and what to write instead.
4
+
5
+ ## Filler and judgment words
6
+
7
+ These words add nothing, or judge difficulty for the reader:
8
+
9
+ | Avoid | Write instead |
10
+ |-------|---------------|
11
+ | simply, simple, just, easy, easily, quick, quickly | Delete the word. |
12
+ | please (in instructions), please note | Delete the word, or state the information directly. |
13
+ | in order to | to |
14
+ | carefully, properly, thoroughly | Describe the check: "Confirm that the output shows `READY`." |
15
+ | currently, now, as of this writing, presently | Delete the word, or give a version number. |
16
+ | latest, new, soon, eventually, in the future | A version number or date. |
17
+ | performant | A precise measure, such as "responds in under 100 ms". |
18
+ | functionality | features, capabilities |
19
+ | leverage, utilize | use |
20
+ | desire, wish | want, need |
21
+ | via | through, by using, with |
22
+ | learnings | lessons, things you learned |
23
+ | allows you to | lets you |
24
+
25
+ ## Ambiguous words
26
+
27
+ These words have more than one meaning:
28
+
29
+ | Avoid | Write instead |
30
+ |-------|---------------|
31
+ | should | must (required), can (optional), or a recommendation: "We recommend…" |
32
+ | may | can (permission or ability), might (possibility) |
33
+ | could, would | can |
34
+ | will | Present tense, unless the event happens later. |
35
+ | once (meaning "after") | after |
36
+ | since, as (meaning "because") | because |
37
+ | while (meaning "although") | although |
38
+ | above, below (positions) | preceding, following, earlier, later |
39
+ | above, below (versions) | later, earlier |
40
+ | this, that (alone) | Add a noun: "this command". |
41
+ | e.g. | for example, such as |
42
+ | i.e. | that is |
43
+ | etc., and so on | Name the items, or introduce the list with "including". |
44
+ | and/or | Rewrite as "A, B, or both". |
45
+ | vice versa | State both directions. |
46
+
47
+ ## Technical terms
48
+
49
+ | Avoid | Write instead |
50
+ |-------|---------------|
51
+ | abort, kill, terminate (generic) | stop, exit, cancel, end |
52
+ | hang, hung | stops responding, isn't responding |
53
+ | hit (a key or button) | press, click |
54
+ | hover over | hold the pointer over, point to |
55
+ | click on | click |
56
+ | check, uncheck, deselect (checkboxes) | select, clear |
57
+ | execute | run, unless "run" is less precise |
58
+ | application | app, except in fixed terms such as "application programming interface" |
59
+ | config | configuration |
60
+ | repo | repository |
61
+ | regex | regular expression |
62
+ | spin up | create, start |
63
+ | deprecated (meaning "removed") | removed. "Deprecated" means still available but not recommended. |
64
+ | disable (for something broken) | unavailable, inactive |
65
+ | display (intransitive) | appear |
66
+ | populate (forms) | fill in |
67
+ | impact (verb) | affect |
68
+ | comprise | consist of, contain, include |
69
+ | log in, login (verb) | sign in, unless the product says "log in" |
70
+ | sign into | sign in to |
71
+ | e-mail | email (not a verb: "send an email") |
72
+ | Id, id | ID |
73
+ | back-end, front-end | backend, frontend |
74
+ | check box | checkbox |
75
+ | drop-down (as a noun) | menu, list |
76
+ | pop-up | dialog, menu |
77
+ | CLI (generic), UI (generic) | Name the specific tool or page. |
78
+ | ssh into | use SSH to connect to |
79
+ | dummy | placeholder, sample |
80
+
81
+ ## Inclusive language
82
+
83
+ | Avoid | Write instead |
84
+ |-------|---------------|
85
+ | whitelist, blacklist | allowlist, denylist or blocklist |
86
+ | master, slave | primary, main, leader, controller; replica, secondary, worker |
87
+ | sanity check | quick check, confidence check |
88
+ | crazy, insane, sane | unexpected, baffling, valid, sensible |
89
+ | cripple | slow down, break |
90
+ | blind to, turn a blind eye | unaware of, ignore |
91
+ | dumb down | simplify |
92
+ | guys, you guys | everyone, folks |
93
+ | he, she (unknown person) | they |
94
+ | man-hours, manpower | person-hours, staff |
95
+ | man-in-the-middle | on-path attacker, person-in-the-middle |
96
+ | guru, ninja, rockstar | expert |
97
+ | native (for people) | Rewrite. For software, use "built-in". |
98
+ | first-class citizen | Describe the specific capability. |
99
+
100
+ ## Spelling and form
101
+
102
+ - **data**: singular mass noun: "the data is", "less data".
103
+ - **internet**: lowercase.
104
+ - **Markdown**: capitalized.
105
+ - **read-only**, **pre-existing**: hyphenated.
106
+ - **runtime** for the environment, **run time** for when code runs.
107
+ - **setup** is a noun; **set up** is a verb.
108
+ - **screenshot** is a noun; the verb is "take a screenshot".
109
+
110
+ ---
111
+
112
+ Adapted from the word list in the [Google developer documentation style guide](https://developers.google.com/style/word-list), licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). This file is a selection; the full list has many more entries.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: grill-me
3
+ description: A relentless interview to sharpen a plan or design.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ Use the `grilling` skill to interview the user about the plan or design they describe.
8
+
9
+ ## Repository conventions first
10
+
11
+ 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. The interview grounds its recommendations in those conventions.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/productivity/grill-me",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Replaced the Claude-specific 'Call the Skill tool' instruction with an agent-neutral one. Added a 'Repository conventions first' section."
8
+ }
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Grill Me"
3
+ short_description: "Sharpen a plan through interview"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -0,0 +1,34 @@
1
+ ---
2
+ name: 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.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/productivity/grilling",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Added a 'Repository conventions first' section."
8
+ }
@@ -0,0 +1,3 @@
1
+ interface:
2
+ display_name: "Grilling"
3
+ short_description: "Stress-test thinking a round of questions at a time"
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: 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.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/productivity/handoff",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Added a 'Repository conventions first' section."
8
+ }
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Handoff"
3
+ short_description: "Compact a conversation into a handoff"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: plan
3
+ description: Plan a change as small, verifiable steps before writing code. Use when the user asks for a plan, or before a feature, refactor, or migration that touches more than one file.
4
+ ---
5
+
6
+ # Plan
7
+
8
+ A plan turns a request into a sequence of **vertical slices**: each slice is a small change that leaves the system working and ends on a check you can run.
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. Plan changes that fit those conventions.
13
+
14
+ ## 1. Pin the goal
15
+
16
+ Restate the goal in one or two sentences, and name the **done criterion**: the observable result that tells the user the work is finished (a passing test, a command's output, a behavior in the UI).
17
+
18
+ Done when the goal and the done criterion fit in three sentences and contain no "and also".
19
+
20
+ ## 2. Gather facts
21
+
22
+ Read the code, tests, configuration, and docs that the change touches. Trace each entry point to the code it reaches. Note the conventions you must follow and the tests that already cover the area.
23
+
24
+ Facts are your job: look them up instead of asking. Done when you can name every file you expect to change and why.
25
+
26
+ ## 3. Surface decisions
27
+
28
+ List the choices that the facts don't settle: behavior in edge cases, trade-offs, naming that users see, anything hard to reverse. Give your recommendation for each one.
29
+
30
+ If the list is long or the decisions depend on each other, use the `grilling` skill to resolve them with the user. Done when every decision has an answer or is marked as an open question in the plan.
31
+
32
+ ## 4. Slice the work
33
+
34
+ Write the steps. For each step, include:
35
+
36
+ - **Change**: what you modify, by file or module.
37
+ - **Check**: the command or observation that proves the step works.
38
+
39
+ Order the steps so that the riskiest unknown comes first, as a **tracer bullet**: the thinnest path through the whole system that proves the approach. Keep refactors in their own steps, separate from behavior changes.
40
+
41
+ Done when every step has a check that can fail, and the last check matches the done criterion.
42
+
43
+ ## 5. Present and wait
44
+
45
+ Show the plan in this shape:
46
+
47
+ ```markdown
48
+ **Goal:** <one sentence>
49
+ **Done when:** <done criterion>
50
+
51
+ 1. <change> → check: <command or observation>
52
+ 2. ...
53
+
54
+ **Open questions:** <none, or the list>
55
+ **Risks:** <what could make the plan wrong>
56
+ ```
57
+
58
+ Wait for the user's approval before you change any file. When the plan changes during the work, update it and say what changed.
@@ -0,0 +1,22 @@
1
+ # Skill mechanics
2
+
3
+ The skill-specific branch of [`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.