1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# agent-skills
8
9A collection of [Agent Skills]; structured markdown that extends LLM
10agent capabilities through a standardised format.
11
12[Agent Skills]: https://agentskills.io/
13
14## Available Skills
15
16Refer to [§ Token stats](#token-stats) for a detailed breakdown of each skill's
17token count, plus overall metadata usage. I've used and tested them most with
18[Crush], [Amp], and [Shelley], and to a lesser degree, [Octofriend] and [Pi].
19
20[Crush]: https://github.com/charmbracelet/crush
21[Amp]: https://ampcode.com
22[Shelley]: https://github.com/boldsoftware/shelley
23[Octofriend]: https://github.com/synthetic-lab/octofriend
24[Pi]: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent
25
26- [addressing-agent-comments](skills/addressing-agent-comments/SKILL.md): Finds
27 `AGENT:` comments in code, gathers feedback, and carries out requested changes
28- [ast-grep](skills/ast-grep/SKILL.md): have the LLM write ast-grep rules to
29 perform structural code search and analysis using the AST
30- [authoring-skills](skills/authoring-skills/SKILL.md): Creates
31 well-structured Agent Skills following best practices. Use when
32 writing new skills, reviewing existing skills, or when the user
33 mentions skill authoring.
34- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
35 Creates tasks in Lunatask for todos, reminders, deferred work, and
36 handoffs.
37- [formatting-commits](skills/formatting-commits/SKILL.md): Creates
38 commits strictly following Conventional Commits format via the
39 `formatted-commit` CLI.
40- [frontend-accessibility](skills/frontend-accessibility/SKILL.md):
41 Generates accessible HTML, React, and frontend code following WCAG 2.2
42 AA guidelines. Focuses on semantic HTML, keyboard accessibility, and
43 screen reader compatibility.
44- [handling-customer-data](skills/handling-customer-data/SKILL.md):
45 Handles customer data responsibly by answering questions about data
46 without ever seeing the data directly.
47- [humanizer](skills/humanizer/SKILL.md): removes signs of AI-generated writing
48 from text, making it sound more natural and human (initially copied from
49 [blader/humanizer] then customised)
50- [invoking-subagents](skills/invoking-subagents/SKILL.md): Invokes
51 ad-hoc subagents to read through lots of data and extract relevant
52 information. Useful for exploring repositories, reading git logs,
53 reviewing large diffs.
54- [managing-and-navigating-worktrees](skills/managing-and-navigating-worktrees/SKILL.md):
55 Manages git worktrees and repos using the wt CLI. Use when cloning or
56 creating new repos, adding worktrees, switching branches.
57- [querying-documentation](skills/querying-documentation/SKILL.md):
58 Spawns focused agents to search specific language/framework
59 documentation and answer moderately complex queries.
60- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
61 Resumes previously deferred work from Lunatask. Use when user pastes a
62 task note, shares a deep link, or references continuing earlier work.
63- [resolving-secrets](skills/resolving-secrets/SKILL.md): Wraps shell
64 commands to resolve secret references in environment variables.
65- [reviewing-code](skills/reviewing-code/SKILL.md): Reviews code for
66 correctness, security, reliability, performance, and quality. Use when
67 asked to review code, a PR, a diff, or changes.
68- [scripting-with-go](skills/scripting-with-go/SKILL.md): Creates
69 executable Go scripts with shebang-like behavior for long-lived
70 automation.
71- [working-with-tmux](skills/working-with-tmux/SKILL.md): Lets the LLM create,
72 manage, and capture output from tmux sessions/windows
73- [writing-roc-lang](skills/writing-roc-lang/SKILL.md): Writes Roc code
74 with strong static types, helpful compiler errors, and functional
75 programming. Covers both full applications and one-off scripts.
76
77[blader/humanizer]: https://github.com/blader/humanizer
78
79## Installation
80
81If you're using [Amp], run `amp skill add
82https://git.secluded.site/agent-skills`. Otherwise, clone the repository, then
83install via `make` or manual symlinks.
84
85[Amp]: https://ampcode.com
86
87```sh
88git clone https://git.secluded.site/agent-skills
89cd agent-skills
90```
91
92### With Make
93
94Skills install to `~/.config/agents/skills/` by default. Override by
95setting `SKILL_DIR`. Tab completion works so you don't have to remember
96skill names or copy/paste.
97
98```sh
99# List available skills
100make list
101
102# Install all skills to default dir
103make all
104
105# Install specific skills to Claude Code
106SKILL_DIR=$HOME/.claude/skills make authoring-skills formatting-commits
107
108# Remove a specific skill from Amp
109make uninstall-authoring-skills SKILL_DIR=$HOME/.config/agents/skills
110
111# Remove all skills from Codex
112make uninstall SKILL_DIR=$HOME/.codex/skills
113```
114
115### With symlinks
116
117```sh
118# Install all skills
119for s in skills/*/; do ln -s "$PWD/$s" ~/.config/agents/skills/; done
120
121# Install specific skills
122ln -s "$PWD/skills/authoring-skills" ~/.config/agents/skills/
123
124# Remove a skill
125rm ~/.config/agents/skills/formatting-commits
126```
127
128### Agent skill directories
129
130| Agent | Dir |
131| --------------------------------------- | -------------------------- |
132| [Crush], [Octofriend], [Shelley], [Amp] | `~/.config/agents/skills/` |
133| [Pi] | `~/.pi/agent/skills/` |
134| Anthropic's Claude Code | `~/.claude/skills/` |
135| OpenAI's Codex | `~/.codex/skills/` |
136
137## Updating
138
139```sh
140cd ~/path/to/agent-skills
141git pull
142```
143
144Symlinked skills update automatically.
145
146## Contributions
147
148Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't
149need a new account to contribute, you don't need to fork this repo, you
150don't need to fiddle with `git send-email`, you don't need to faff with
151your email client to get `git request-pull` working...
152
153You just need:
154
155- Git
156- SSH
157- An SSH key
158
159```sh
160# Clone this repo, make your changes, and commit them
161# Create a new patch request with
162git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
163# After potential feedback, submit a revision to an existing patch request with
164git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
165# List patch requests
166ssh pr.pico.sh pr ls amolith/llm-projects
167```
168
169See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
170complete example workflow.
171
172[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
173[pr.pico.sh]: https://pr.pico.sh
174
175## Token stats
176
177Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens] endpoint with [./skill-stats.go](./skill-stats.go).
178
179[Synthetic.new]: https://synthetic.new
180[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens
181
182```
183=== addressing-agent-comments ===
184
185Token breakdown:
186 Name: 22 tokens
187 Description: 96 tokens
188 Body: 706 tokens (40 lines)
189 ───────────────────────────────────────────────
190 Total: 824 tokens
191
192=== ast-grep ===
193
194Token breakdown:
195 Name: 18 tokens
196 Description: 198 tokens
197 Body: 7503 tokens (469 lines)
198 References:
199 rule_reference.md 6814 tokens
200 ───────────────────────────────────────────────
201 Total: 14533 tokens
202 ⚠️ Body exceeds recommended 5000 token budget!
203
204=== authoring-skills ===
205
206Token breakdown:
207 Name: 20 tokens
208 Description: 86 tokens
209 Body: 2000 tokens (102 lines)
210 References:
211 checklist.md 806 tokens
212 patterns.md 2415 tokens
213 process.md 833 tokens
214 specification.md 3890 tokens
215 ───────────────────────────────────────────────
216 Total: 10050 tokens
217
218=== creating-tasks-through-lunatask ===
219
220Token breakdown:
221 Name: 30 tokens
222 Description: 108 tokens
223 Body: 1927 tokens (88 lines)
224 References:
225 cli.md 589 tokens
226 handoff.md 2769 tokens
227 installing-lune.md 176 tokens
228 ───────────────────────────────────────────────
229 Total: 5599 tokens
230
231=== formatting-commits ===
232
233Token breakdown:
234 Name: 22 tokens
235 Description: 98 tokens
236 Body: 992 tokens (43 lines)
237 References:
238 installing-git-format.md 64 tokens
239 ───────────────────────────────────────────────
240 Total: 1176 tokens
241
242=== frontend-accessibility ===
243
244Token breakdown:
245 Name: 20 tokens
246 Description: 140 tokens
247 Body: 2891 tokens (148 lines)
248 References:
249 antipatterns.md 3638 tokens
250 patterns.md 6233 tokens
251 ───────────────────────────────────────────────
252 Total: 12922 tokens
253
254=== handling-customer-data ===
255
256Token breakdown:
257 Name: 22 tokens
258 Description: 123 tokens
259 Body: 1983 tokens (107 lines)
260 ───────────────────────────────────────────────
261 Total: 2128 tokens
262
263=== humanizer ===
264
265Token breakdown:
266 Name: 15 tokens
267 Description: 84 tokens
268 Body: 8536 tokens (462 lines)
269 ───────────────────────────────────────────────
270 Total: 8635 tokens
271 ⚠️ Body exceeds recommended 5000 token budget!
272
273=== invoking-subagents ===
274
275Token breakdown:
276 Name: 20 tokens
277 Description: 113 tokens
278 Body: 796 tokens (13 lines)
279 References:
280 installing-synu.md 140 tokens
281 ───────────────────────────────────────────────
282 Total: 1069 tokens
283
284=== managing-and-navigating-worktrees ===
285
286Token breakdown:
287 Name: 32 tokens
288 Description: 110 tokens
289 Body: 1912 tokens (96 lines)
290 ───────────────────────────────────────────────
291 Total: 2054 tokens
292
293=== querying-documentation ===
294
295Token breakdown:
296 Name: 22 tokens
297 Description: 132 tokens
298 Body: 796 tokens (22 lines)
299 References:
300 dependencies.md 108 tokens
301 ───────────────────────────────────────────────
302 Total: 1058 tokens
303
304=== rebasing-with-git ===
305
306Token breakdown:
307 Name: 22 tokens
308 Description: 188 tokens
309 Body: 5696 tokens (202 lines)
310 ───────────────────────────────────────────────
311 Total: 5906 tokens
312 ⚠️ Body exceeds recommended 5000 token budget!
313
314=== resolving-secrets ===
315
316Token breakdown:
317 Name: 20 tokens
318 Description: 120 tokens
319 Body: 259 tokens (10 lines)
320 References:
321 installing-opx.md 125 tokens
322 ───────────────────────────────────────────────
323 Total: 524 tokens
324
325=== resuming-work-through-lunatask ===
326
327Token breakdown:
328 Name: 30 tokens
329 Description: 113 tokens
330 Body: 1241 tokens (42 lines)
331 References:
332 cli.md 528 tokens
333 installing-lune.md 176 tokens
334 ───────────────────────────────────────────────
335 Total: 2088 tokens
336
337=== reviewing-code ===
338
339Token breakdown:
340 Name: 18 tokens
341 Description: 125 tokens
342 Body: 1880 tokens (121 lines)
343 ───────────────────────────────────────────────
344 Total: 2023 tokens
345
346=== scripting-with-go ===
347
348Token breakdown:
349 Name: 20 tokens
350 Description: 120 tokens
351 Body: 1968 tokens (138 lines)
352 ───────────────────────────────────────────────
353 Total: 2108 tokens
354
355=== working-with-tmux ===
356
357Token breakdown:
358 Name: 22 tokens
359 Description: 84 tokens
360 Body: 1465 tokens (87 lines)
361 ───────────────────────────────────────────────
362 Total: 1571 tokens
363
364=== writing-git-tags ===
365
366Token breakdown:
367 Name: 22 tokens
368 Description: 101 tokens
369 Body: 2232 tokens (107 lines)
370 References:
371 installing-git-format.md 64 tokens
372 ───────────────────────────────────────────────
373 Total: 2419 tokens
374
375=== writing-roc-lang ===
376
377Token breakdown:
378 Name: 22 tokens
379 Description: 142 tokens
380 Body: 1846 tokens (117 lines)
381 References:
382 builtins-llms.md 67881 tokens
383 llms.md 11324 tokens
384 scripting.md 1722 tokens
385 ───────────────────────────────────────────────
386 Total: 82937 tokens
387
388============================================================
389SUMMARY
390============================================================
391
392Skills: 19
393Metadata: 2700 tokens
394Combined bodies: 46629 tokens
395Overall: 159624 tokens
396Validation errors: 0
397
398Largest skills (by total tokens):
399 1. writing-roc-lang 82937 tokens
400 2. ast-grep 14533 tokens
401 3. frontend-accessibility 12922 tokens
402 4. authoring-skills 10050 tokens
403 5. humanizer 8635 tokens
404```
405
406---
407
408Some other tools if these interested you
409
410- [wt](https://git.secluded.site/wt) - CLI for managing git worktrees
411- [formatted-commit](https://git.secluded.site/formatted-commit) - CLI that turns LLM input into well-formatted Conventional Commits
412- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix typos, translate, reformat)
413- [lune](https://git.secluded.site/lune) - CLI and MCP server for [Lunatask.app](https://lunatask.app)