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- [working-with-tmux](skills/working-with-tmux/SKILL.md): Spawns and manages
82 background processes via tmux. Creates windows, sends commands, and captures
83 output without blocking the main session. Useful for servers and long tasks.
84- [writing-git-tags](skills/writing-git-tags/SKILL.md): Generates git tag
85 annotations from commit history following Semantic Versioning and Conventional
86 Commits via [git-format].
87- [writing-roc-lang](skills/writing-roc-lang/SKILL.md): Writes Roc code with
88 strong static types, helpful compiler errors, and functional programming.
89 Covers both full applications and one-off scripts.
90- [writing-rust](skills/writing-rust/SKILL.md): Writes idiomatic Rust with
91 strict quality gates: `cargo fmt`, `clippy -- -D warnings`, and required
92 tests. Enforces `thiserror` for libs, `anyhow` for apps, warns against common
93 anti-patterns.
94
95[blader/humanizer]: https://github.com/blader/humanizer
96[ast-grep]: https://github.com/ast-grep/ast-grep
97[git-format]: https://git.secluded.site/git-format
98[lune]: https://git.secluded.site/lune
99[Lunatask]: https://lunatask.app/
100[ntfy.sh]: https://ntfy.sh
101[rumilo]: https://git.secluded.site/rumilo
102[synu]: https://git.secluded.site/synu
103[wt]: https://git.secluded.site/wt
104[gum]: https://github.com/charmbracelet/gum
105
106## Installation
107
108If you're using [Amp], run `amp skill add
109https://git.secluded.site/agent-skills`. Otherwise, clone the repository, then
110install via `make` or manual symlinks.
111
112[Amp]: https://ampcode.com
113
114```sh
115git clone https://git.secluded.site/agent-skills
116cd agent-skills
117```
118
119### With Make
120
121Skills install to `~/.config/agents/skills/` by default. Override by
122setting `SKILL_DIR`. Tab completion works so you don't have to remember
123skill names or copy/paste.
124
125```sh
126# List available skills
127make list
128
129# Install all skills to default dir
130make all
131
132# Install specific skills to Claude Code
133SKILL_DIR=$HOME/.claude/skills make authoring-skills formatting-commits
134
135# Remove a specific skill from Amp
136make uninstall-authoring-skills SKILL_DIR=$HOME/.config/agents/skills
137
138# Remove all skills from Codex
139make uninstall SKILL_DIR=$HOME/.codex/skills
140```
141
142### With symlinks
143
144```sh
145# Install all skills
146for s in skills/*/; do ln -s "$PWD/$s" ~/.config/agents/skills/; done
147
148# Install specific skills
149ln -s "$PWD/skills/authoring-skills" ~/.config/agents/skills/
150
151# Remove a skill
152rm ~/.config/agents/skills/formatting-commits
153```
154
155### Agent skill directories
156
157| Agent | Dir |
158| --------------------------------------- | -------------------------- |
159| [Crush], [Octofriend], [Shelley], [Amp] | `~/.config/agents/skills/` |
160| [Pi] | `~/.pi/agent/skills/` |
161| Anthropic's Claude Code | `~/.claude/skills/` |
162| OpenAI's Codex | `~/.codex/skills/` |
163
164## Updating
165
166```sh
167cd ~/path/to/agent-skills
168git pull
169```
170
171Symlinked skills update automatically.
172
173## Contributions
174
175Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
176new account to contribute, you don't need to fork this repo, you don't need to
177fiddle with `git send-email`, you don't need to faff with your email client to
178get `git request-pull` working...
179
180You just need:
181
182- Git
183- SSH
184- An SSH key
185
186```sh
187# Clone this repo, make your changes, and commit them
188# Create a new patch request with
189git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
190# After potential feedback, submit a revision to an existing patch request with
191git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
192# List patch requests
193ssh pr.pico.sh pr ls amolith/llm-projects
194```
195
196See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
197complete example workflow.
198
199[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
200[pr.pico.sh]: https://pr.pico.sh
201
202## Token stats
203
204Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens]
205endpoint with [./skill-stats.go](./skill-stats.go).
206
207[Synthetic.new]: https://synthetic.new
208[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens
209
210```
211=== addressing-agent-comments ===
212
213Token breakdown:
214 Name: 22 tokens
215 Description: 96 tokens
216 Body: 706 tokens (40 lines)
217 ───────────────────────────────────────────────
218 Total: 824 tokens
219
220=== ast-grep ===
221
222Token breakdown:
223 Name: 18 tokens
224 Description: 198 tokens
225 Body: 7503 tokens (469 lines)
226 References:
227 rule_reference.md 6814 tokens
228 ───────────────────────────────────────────────
229 Total: 14533 tokens
230 ⚠️ Body exceeds recommended 5000 token budget!
231
232=== auditing-repositories ===
233
234Token breakdown:
235 Name: 20 tokens
236 Description: 140 tokens
237 Body: 2840 tokens (156 lines)
238 References:
239 llm-security.md 1138 tokens
240 ───────────────────────────────────────────────
241 Total: 4138 tokens
242
243=== authoring-skills ===
244
245Token breakdown:
246 Name: 20 tokens
247 Description: 86 tokens
248 Body: 2000 tokens (102 lines)
249 References:
250 checklist.md 806 tokens
251 patterns.md 2415 tokens
252 process.md 833 tokens
253 specification.md 3890 tokens
254 ───────────────────────────────────────────────
255 Total: 10050 tokens
256
257=== collaborating-through-pr-pico-sh ===
258
259Token breakdown:
260 Name: 30 tokens
261 Description: 120 tokens
262 Body: 1260 tokens (42 lines)
263 References:
264 contributing.md 435 tokens
265 reviewing.md 1080 tokens
266 ───────────────────────────────────────────────
267 Total: 2925 tokens
268
269=== creating-tasks-through-lunatask ===
270
271Token breakdown:
272 Name: 30 tokens
273 Description: 108 tokens
274 Body: 1841 tokens (84 lines)
275 References:
276 cli.md 589 tokens
277 handoff.md 2769 tokens
278 installing-lune.md 176 tokens
279 ───────────────────────────────────────────────
280 Total: 5513 tokens
281
282=== formatting-commits ===
283
284Token breakdown:
285 Name: 22 tokens
286 Description: 98 tokens
287 Body: 992 tokens (43 lines)
288 References:
289 installing-git-format.md 64 tokens
290 ───────────────────────────────────────────────
291 Total: 1176 tokens
292
293=== frontend-accessibility ===
294
295Token breakdown:
296 Name: 20 tokens
297 Description: 140 tokens
298 Body: 2891 tokens (148 lines)
299 References:
300 antipatterns.md 3638 tokens
301 patterns.md 6233 tokens
302 ───────────────────────────────────────────────
303 Total: 12922 tokens
304
305=== handling-customer-data ===
306
307Token breakdown:
308 Name: 22 tokens
309 Description: 123 tokens
310 Body: 1983 tokens (107 lines)
311 ───────────────────────────────────────────────
312 Total: 2128 tokens
313
314=== humanizer ===
315
316Token breakdown:
317 Name: 15 tokens
318 Description: 84 tokens
319 Body: 8536 tokens (462 lines)
320 ───────────────────────────────────────────────
321 Total: 8635 tokens
322 ⚠️ Body exceeds recommended 5000 token budget!
323
324=== invoking-subagents ===
325
326Token breakdown:
327 Name: 20 tokens
328 Description: 113 tokens
329 Body: 796 tokens (13 lines)
330 References:
331 installing-synu.md 140 tokens
332 ───────────────────────────────────────────────
333 Total: 1069 tokens
334
335=== managing-and-navigating-worktrees ===
336
337Token breakdown:
338 Name: 32 tokens
339 Description: 164 tokens
340 Body: 1912 tokens (96 lines)
341 ───────────────────────────────────────────────
342 Total: 2108 tokens
343
344=== notifying-through-ntfy ===
345
346Token breakdown:
347 Name: 25 tokens
348 Description: 93 tokens
349 Body: 2884 tokens (89 lines)
350 References:
351 ht.md 1063 tokens
352 httpie.md 1067 tokens
353 nodejs.md 1497 tokens
354 python.md 1468 tokens
355 wget.md 1216 tokens
356 ───────────────────────────────────────────────
357 Total: 9313 tokens
358
359=== rebasing-with-git ===
360
361Token breakdown:
362 Name: 22 tokens
363 Description: 188 tokens
364 Body: 6282 tokens (232 lines)
365 ───────────────────────────────────────────────
366 Total: 6492 tokens
367 ⚠️ Body exceeds recommended 5000 token budget!
368
369=== researching-with-rumilo ===
370
371Token breakdown:
372 Name: 25 tokens
373 Description: 159 tokens
374 Body: 3082 tokens (111 lines)
375 ───────────────────────────────────────────────
376 Total: 3266 tokens
377
378=== resuming-work-through-lunatask ===
379
380Token breakdown:
381 Name: 30 tokens
382 Description: 113 tokens
383 Body: 1241 tokens (42 lines)
384 References:
385 cli.md 528 tokens
386 installing-lune.md 176 tokens
387 ───────────────────────────────────────────────
388 Total: 2088 tokens
389
390=== reviewing-code ===
391
392Token breakdown:
393 Name: 18 tokens
394 Description: 132 tokens
395 Body: 970 tokens (48 lines)
396 ───────────────────────────────────────────────
397 Total: 1120 tokens
398
399=== scripting-with-go ===
400
401Token breakdown:
402 Name: 20 tokens
403 Description: 120 tokens
404 Body: 1968 tokens (138 lines)
405 ───────────────────────────────────────────────
406 Total: 2108 tokens
407
408=== working-with-tmux ===
409
410Token breakdown:
411 Name: 22 tokens
412 Description: 84 tokens
413 Body: 1465 tokens (87 lines)
414 ───────────────────────────────────────────────
415 Total: 1571 tokens
416
417=== writing-git-tags ===
418
419Token breakdown:
420 Name: 22 tokens
421 Description: 101 tokens
422 Body: 2232 tokens (107 lines)
423 References:
424 installing-git-format.md 64 tokens
425 ───────────────────────────────────────────────
426 Total: 2419 tokens
427
428=== writing-roc-lang ===
429
430Token breakdown:
431 Name: 22 tokens
432 Description: 142 tokens
433 Body: 1846 tokens (117 lines)
434 References:
435 builtins-llms.md 67881 tokens
436 llms.md 11324 tokens
437 scripting.md 1722 tokens
438 ───────────────────────────────────────────────
439 Total: 82937 tokens
440
441=== writing-rust ===
442
443Token breakdown:
444 Name: 18 tokens
445 Description: 120 tokens
446 Body: 3628 tokens (139 lines)
447 References:
448 idioms.md 4605 tokens
449 ───────────────────────────────────────────────
450 Total: 8371 tokens
451
452============================================================
453SUMMARY
454============================================================
455
456Skills: 22
457Metadata: 3217 tokens
458Combined bodies: 58858 tokens
459Overall: 185706 tokens
460Validation errors: 0
461
462Largest skills (by total tokens):
463 1. writing-roc-lang 82937 tokens
464 2. ast-grep 14533 tokens
465 3. frontend-accessibility 12922 tokens
466 4. authoring-skills 10050 tokens
467 5. notifying-through-ntfy 9313 tokens
468```
469
470---
471
472Some other tools if these interested you
473
474- [wt](https://git.secluded.site/wt) - CLI for managing git worktrees
475- [git-format](https://git.secluded.site/git-format) - CLI that turns LLM input
476 into well-formatted conventional commits and tags
477- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix
478 typos, translate, reformat)
479- [lune](https://git.secluded.site/lune) - CLI and MCP server for
480 [Lunatask.app](https://lunatask.app)