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
28 changes.
29- [ast-grep](skills/ast-grep/SKILL.md): Writes [ast-grep] rules for structural
30 code search and modification.
31- [auditing-repositories](skills/auditing-repositories/SKILL.md): Audits open
32 source repositories for security, privacy, and unexpected behavior.
33- [authoring-skills](skills/authoring-skills/SKILL.md): Creates and reviews
34 Agent Skills following best practices. Covers skill structure, frontmatter,
35 and progressive disclosure patterns.
36- [collaborating-through-pr-pico-sh](skills/collaborating-through-pr-pico-sh/SKILL.md):
37 Collaborates on git patches via [pr.pico.sh], a minimal patchbin service.
38 Covers both contributing and reviewing patch requests using `git format-patch`
39 and `git am`.
40- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
41 Creates tasks and handoffs in [Lunatask] via [lune]. Tasks are just tasks.
42 Handoffs capture work to resume later across sessions without filling context
43 windows.
44- [formatting-commits](skills/formatting-commits/SKILL.md): Creates commits
45 following Conventional Commits format via [git-format].
46- [frontend-accessibility](skills/frontend-accessibility/SKILL.md): Strives to
47 generate accessible HTML, React, and frontend code following WCAG 2.2 AA.
48 Prioritizes semantic HTML over ARIA, keyboard navigation, and screen reader
49 compatibility.
50- [handling-customer-data](skills/handling-customer-data/SKILL.md): Queries
51 customer data responsibly—the agent answers questions about the data without
52 ever seeing it directly.
53- [humanizer](skills/humanizer/SKILL.md): Removes AI-generated patterns from
54 text like promotional fluff, weasel words, and mechanical sentence structures.
55 Based on Wikipedia's AI Cleanup research. Originally from [blader/humanizer].
56- [invoking-subagents](skills/invoking-subagents/SKILL.md): Spawns subagents
57 with restricted tool access for parallel tasks across repositories. Requires
58 [synu] and the `claude` CLI. Useful for summarizing git history or processing
59 large diffs without filling the main context window.
60- [managing-and-navigating-worktrees](skills/managing-and-navigating-worktrees/SKILL.md):
61 Manages git worktrees using [wt] with a bare repository structure. Each branch
62 lives in its own sibling directory. Requires [wt], git, and [gum].
63- [notifying-through-ntfy](skills/notifying-through-ntfy/SKILL.md): Sends push
64 notifications via [ntfy.sh] when requested, such as at the end of its turn.
65- [rebasing-with-git](skills/rebasing-with-git/SKILL.md): Manages git rebase
66 workflows from simple rebases to the drop-and-repick integration branch
67 pattern. Assumes `upstream` remote for forks and `rerere` enabled. Supports
68 worktrees including `wt`-managed repos.
69- [researching-with-rumilo](skills/researching-with-rumilo/SKILL.md): Dispatches
70 AI research subagents via [rumilo] for web search and repository exploration.
71 Research topics, look up library usage, or explore external codebases without
72 filling the main context window.
73- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
74 Resumes deferred work from [Lunatask] handoff notes via [lune].
75- [reviewing-code](skills/reviewing-code/SKILL.md): Reviews changes, commits,
76 PRs, and patches using Kodus, CodeRabbit, or Amp, preferring whichever is
77 available in that order.
78- [scripting-with-go](skills/scripting-with-go/SKILL.md): Creates executable Go
79 scripts using a shell trick (not a true shebang). For automation and tooling
80 outside of Go projects.
81- [testing-with-gocuke-and-gherkin](skills/testing-with-gocuke-and-gherkin/SKILL.md):
82 Drives BDD, red/green TDD, and property-based testing in Go projects using
83 [gocuke] and Gherkin feature files.
84- [working-with-tmux](skills/working-with-tmux/SKILL.md): Spawns and manages
85 background processes via tmux. Creates windows, sends commands, and captures
86 output without blocking the main session. Useful for servers and long tasks.
87- [writing-git-tags](skills/writing-git-tags/SKILL.md): Generates git tag
88 annotations from commit history following Semantic Versioning and Conventional
89 Commits via [git-format].
90- [writing-roc-lang](skills/writing-roc-lang/SKILL.md): Writes Roc code with
91 strong static types, helpful compiler errors, and functional programming.
92 Covers both full applications and one-off scripts.
93- [writing-rust](skills/writing-rust/SKILL.md): Writes idiomatic Rust with
94 strict quality gates: `cargo fmt`, `clippy -- -D warnings`, and required
95 tests. Enforces `thiserror` for libs, `anyhow` for apps, warns against common
96 anti-patterns.
97
98[blader/humanizer]: https://github.com/blader/humanizer
99[ast-grep]: https://github.com/ast-grep/ast-grep
100[git-format]: https://git.secluded.site/git-format
101[gocuke]: https://github.com/tenntenn/gocuke
102[lune]: https://git.secluded.site/lune
103[Lunatask]: https://lunatask.app/
104[ntfy.sh]: https://ntfy.sh
105[rumilo]: https://git.secluded.site/rumilo
106[synu]: https://git.secluded.site/synu
107[wt]: https://git.secluded.site/wt
108[gum]: https://github.com/charmbracelet/gum
109
110## Installation
111
112If you're using [Amp], run `amp skill add
113https://git.secluded.site/agent-skills`. Otherwise, clone the repository, then
114install via `make` or manual symlinks.
115
116[Amp]: https://ampcode.com
117
118```sh
119git clone https://git.secluded.site/agent-skills
120cd agent-skills
121```
122
123### With Make
124
125Skills install to `~/.config/agents/skills/` by default. Override by
126setting `SKILL_DIR`. Tab completion works so you don't have to remember
127skill names or copy/paste.
128
129```sh
130# List available skills
131make list
132
133# Install all skills to default dir
134make all
135
136# Install specific skills to Claude Code
137SKILL_DIR=$HOME/.claude/skills make authoring-skills formatting-commits
138
139# Remove a specific skill from Amp
140make uninstall-authoring-skills SKILL_DIR=$HOME/.config/agents/skills
141
142# Remove all skills from Codex
143make uninstall SKILL_DIR=$HOME/.codex/skills
144```
145
146### With symlinks
147
148```sh
149# Install all skills
150for s in skills/*/; do ln -s "$PWD/$s" ~/.config/agents/skills/; done
151
152# Install specific skills
153ln -s "$PWD/skills/authoring-skills" ~/.config/agents/skills/
154
155# Remove a skill
156rm ~/.config/agents/skills/formatting-commits
157```
158
159### Agent skill directories
160
161| Agent | Dir |
162| --------------------------------------- | -------------------------- |
163| [Crush], [Octofriend], [Shelley], [Amp] | `~/.config/agents/skills/` |
164| [Pi] | `~/.pi/agent/skills/` |
165| Anthropic's Claude Code | `~/.claude/skills/` |
166| OpenAI's Codex | `~/.codex/skills/` |
167
168## Updating
169
170```sh
171cd ~/path/to/agent-skills
172git pull
173```
174
175Symlinked skills update automatically.
176
177## Contributions
178
179Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
180new account to contribute, you don't need to fork this repo, you don't need to
181fiddle with `git send-email`, you don't need to faff with your email client to
182get `git request-pull` working...
183
184You just need:
185
186- Git
187- SSH
188- An SSH key
189
190```sh
191# Clone this repo, make your changes, and commit them
192# Create a new patch request with
193git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
194# After potential feedback, submit a revision to an existing patch request with
195git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
196# List patch requests
197ssh pr.pico.sh pr ls amolith/llm-projects
198```
199
200See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
201complete example workflow.
202
203[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
204[pr.pico.sh]: https://pr.pico.sh
205
206## Token stats
207
208Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens]
209endpoint with [./skill-stats.go](./skill-stats.go).
210
211[Synthetic.new]: https://synthetic.new
212[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens
213
214```
215=== addressing-agent-comments ===
216
217Token breakdown:
218 Name: 8 tokens
219 Description: 36 tokens
220 Body: 271 tokens (40 lines)
221 ───────────────────────────────────────────────
222 Total: 315 tokens
223
224=== ast-grep ===
225
226Token breakdown:
227 Name: 7 tokens
228 Description: 76 tokens
229 Body: 2765 tokens (469 lines)
230 References:
231 rule_reference.md 2515 tokens
232 ───────────────────────────────────────────────
233 Total: 5363 tokens
234
235=== auditing-repositories ===
236
237Token breakdown:
238 Name: 8 tokens
239 Description: 51 tokens
240 Body: 1046 tokens (156 lines)
241 References:
242 llm-security.md 427 tokens
243 ───────────────────────────────────────────────
244 Total: 1532 tokens
245
246=== authoring-skills ===
247
248Token breakdown:
249 Name: 8 tokens
250 Description: 32 tokens
251 Body: 733 tokens (102 lines)
252 References:
253 checklist.md 301 tokens
254 patterns.md 880 tokens
255 process.md 311 tokens
256 specification.md 1441 tokens
257 ───────────────────────────────────────────────
258 Total: 3706 tokens
259
260=== collaborating-through-pr-pico-sh ===
261
262Token breakdown:
263 Name: 12 tokens
264 Description: 47 tokens
265 Body: 521 tokens (43 lines)
266 References:
267 contributing.md 162 tokens
268 jujutsu.md 516 tokens
269 reviewing.md 406 tokens
270 ───────────────────────────────────────────────
271 Total: 1664 tokens
272
273=== creating-tasks-through-lunatask ===
274
275Token breakdown:
276 Name: 12 tokens
277 Description: 41 tokens
278 Body: 687 tokens (84 lines)
279 References:
280 cli.md 218 tokens
281 handoff.md 1035 tokens
282 installing-lune.md 65 tokens
283 ───────────────────────────────────────────────
284 Total: 2058 tokens
285
286=== formatting-commits ===
287
288Token breakdown:
289 Name: 8 tokens
290 Description: 37 tokens
291 Body: 361 tokens (43 lines)
292 References:
293 installing-git-format.md 22 tokens
294 ───────────────────────────────────────────────
295 Total: 428 tokens
296
297=== frontend-accessibility ===
298
299Token breakdown:
300 Name: 7 tokens
301 Description: 52 tokens
302 Body: 1080 tokens (148 lines)
303 References:
304 antipatterns.md 1341 tokens
305 patterns.md 2279 tokens
306 ───────────────────────────────────────────────
307 Total: 4759 tokens
308
309=== handling-customer-data ===
310
311Token breakdown:
312 Name: 9 tokens
313 Description: 46 tokens
314 Body: 718 tokens (107 lines)
315 ───────────────────────────────────────────────
316 Total: 773 tokens
317
318=== humanizer ===
319
320Token breakdown:
321 Name: 6 tokens
322 Description: 31 tokens
323 Body: 3274 tokens (462 lines)
324 ───────────────────────────────────────────────
325 Total: 3311 tokens
326
327=== invoking-subagents ===
328
329Token breakdown:
330 Name: 8 tokens
331 Description: 42 tokens
332 Body: 227 tokens (16 lines)
333 ───────────────────────────────────────────────
334 Total: 277 tokens
335
336=== managing-and-navigating-worktrees ===
337
338Token breakdown:
339 Name: 11 tokens
340 Description: 60 tokens
341 Body: 703 tokens (96 lines)
342 ───────────────────────────────────────────────
343 Total: 774 tokens
344
345=== notifying-through-ntfy ===
346
347Token breakdown:
348 Name: 10 tokens
349 Description: 37 tokens
350 Body: 1052 tokens (89 lines)
351 References:
352 ht.md 383 tokens
353 httpie.md 385 tokens
354 nodejs.md 541 tokens
355 python.md 517 tokens
356 wget.md 430 tokens
357 ───────────────────────────────────────────────
358 Total: 3355 tokens
359
360=== rebasing-with-git ===
361
362Token breakdown:
363 Name: 8 tokens
364 Description: 71 tokens
365 Body: 2317 tokens (232 lines)
366 ───────────────────────────────────────────────
367 Total: 2396 tokens
368
369=== researching-with-rumilo ===
370
371Token breakdown:
372 Name: 10 tokens
373 Description: 60 tokens
374 Body: 1152 tokens (111 lines)
375 ───────────────────────────────────────────────
376 Total: 1222 tokens
377
378=== resuming-work-through-lunatask ===
379
380Token breakdown:
381 Name: 12 tokens
382 Description: 44 tokens
383 Body: 466 tokens (42 lines)
384 References:
385 cli.md 195 tokens
386 installing-lune.md 65 tokens
387 ───────────────────────────────────────────────
388 Total: 782 tokens
389
390=== reviewing-code ===
391
392Token breakdown:
393 Name: 7 tokens
394 Description: 51 tokens
395 Body: 355 tokens (48 lines)
396 ───────────────────────────────────────────────
397 Total: 413 tokens
398
399=== scripting-with-go ===
400
401Token breakdown:
402 Name: 8 tokens
403 Description: 46 tokens
404 Body: 727 tokens (138 lines)
405 ───────────────────────────────────────────────
406 Total: 781 tokens
407
408=== testing-with-gocuke-and-gherkin ===
409
410Token breakdown:
411 Name: 14 tokens
412 Description: 73 tokens
413 Body: 1188 tokens (105 lines)
414 References:
415 bdd-practices.md 1035 tokens
416 gherkin-reference.md 984 tokens
417 gocuke-api.md 1427 tokens
418 ───────────────────────────────────────────────
419 Total: 4721 tokens
420
421=== working-with-tmux ===
422
423Token breakdown:
424 Name: 8 tokens
425 Description: 32 tokens
426 Body: 544 tokens (87 lines)
427 ───────────────────────────────────────────────
428 Total: 584 tokens
429
430=== writing-git-tags ===
431
432Token breakdown:
433 Name: 7 tokens
434 Description: 38 tokens
435 Body: 821 tokens (107 lines)
436 References:
437 installing-git-format.md 22 tokens
438 ───────────────────────────────────────────────
439 Total: 888 tokens
440
441=== writing-roc-lang ===
442
443Token breakdown:
444 Name: 8 tokens
445 Description: 53 tokens
446 Body: 693 tokens (117 lines)
447 References:
448 builtins-llms.md 25216 tokens
449 llms.md 4253 tokens
450 scripting.md 614 tokens
451 ───────────────────────────────────────────────
452 Total: 30837 tokens
453
454=== writing-rust ===
455
456Token breakdown:
457 Name: 7 tokens
458 Description: 45 tokens
459 Body: 1324 tokens (139 lines)
460 References:
461 idioms.md 1708 tokens
462 ───────────────────────────────────────────────
463 Total: 3084 tokens
464
465============================================================
466SUMMARY
467============================================================
468
469Skills: 23
470Metadata: 1304 tokens
471Combined bodies: 23025 tokens
472Overall: 74023 tokens
473Validation errors: 0
474
475Largest skills (by total tokens):
476 1. writing-roc-lang 30837 tokens
477 2. ast-grep 5363 tokens
478 3. frontend-accessibility 4759 tokens
479 4. testing-with-gocuke-and-gherkin 4721 tokens
480 5. authoring-skills 3706 tokens
481```
482
483---
484
485Some other tools if these interested you
486
487- [wt](https://git.secluded.site/wt) - CLI for managing git worktrees
488- [git-format](https://git.secluded.site/git-format) - CLI that turns LLM input
489 into well-formatted conventional commits and tags
490- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix
491 typos, translate, reformat)
492- [lune](https://git.secluded.site/lune) - CLI and MCP server for
493 [Lunatask.app](https://lunatask.app)