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): Write [ast-grep] rules for structural
30 code search and analysis. Find patterns the way the compiler sees them, not
31 just as text.
32- [authoring-skills](skills/authoring-skills/SKILL.md): Create and review Agent
33 Skills following best practices. Covers skill structure, frontmatter, and
34 progressive disclosure patterns.
35- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
36 Create tasks and handoffs in [Lunatask] via [lune]. Tasks are just tasks.
37 Handoffs capture work to resume later across sessions without filling context
38 windows.
39- [formatting-commits](skills/formatting-commits/SKILL.md): Create commits
40 following Conventional Commits format via [git-format].
41- [frontend-accessibility](skills/frontend-accessibility/SKILL.md): Generate
42 accessible HTML, React, and frontend code following WCAG 2.2 AA. Prioritizes
43 semantic HTML over ARIA, keyboard navigation, and screen reader compatibility.
44- [handling-customer-data](skills/handling-customer-data/SKILL.md): Query
45 customer data responsibly—the agent answers questions about the data without
46 ever seeing it directly.
47- [humanizer](skills/humanizer/SKILL.md): Remove AI-generated patterns from text
48 like promotional fluff, weasel words, and mechanical sentence structures.
49 Based on Wikipedia's AI Cleanup research. Originally from [blader/humanizer].
50- [invoking-subagents](skills/invoking-subagents/SKILL.md): Spawn subagents with
51 restricted tool access for parallel tasks across repositories. Requires [synu]
52 and the `claude` CLI. Useful for summarizing git history or processing large
53 diffs without filling the main context window.
54- [managing-and-navigating-worktrees](skills/managing-and-navigating-worktrees/SKILL.md):
55 Git worktree management using [wt] with a bare repository structure. Each
56 branch lives in its own sibling directory. Requires [wt], git, and [gum].
57- [querying-documentation](skills/querying-documentation/SKILL.md): Query Go
58 documentation with focused subagents for complex questions spanning multiple
59 packages or external libraries. Requires Fish shell and [synu]. Currently
60 Go-only.
61- [rebasing-with-git](skills/rebasing-with-git/SKILL.md): Git rebase workflows
62 from simple rebases to the drop-and-repick integration branch pattern. Assumes
63 `upstream` remote for forks and `rerere` enabled. Supports worktrees including
64 `wt`-managed repos.
65- [researching-with-rumilo](skills/researching-with-rumilo/SKILL.md): Dispatch AI
66 research subagents via [rumilo] for web search and repository exploration.
67 Research topics, look up library usage, or explore external codebases without
68 filling the main context window.
69- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
70 Resume deferred work from [Lunatask] handoff notes via [lune].
71- [reviewing-code](skills/reviewing-code/SKILL.md): Review code for correctness,
72 security, reliability, performance, and quality. Covers PRs, diffs, and
73 general change review.
74- [scripting-with-go](skills/scripting-with-go/SKILL.md): Create executable Go
75 scripts using a shell trick (not a true shebang). For automation and tooling
76 outside of Go projects.
77- [working-with-tmux](skills/working-with-tmux/SKILL.md): Spawn and manage
78 background processes via tmux. Create windows, send commands, and capture
79 output without blocking the main session. Useful for servers and long tasks.
80- [writing-git-tags](skills/writing-git-tags/SKILL.md): Generate git tag
81 annotations from commit history following Semantic Versioning and Conventional
82 Commits via [git-format].
83- [writing-roc-lang](skills/writing-roc-lang/SKILL.md): Write Roc code with
84 strong static types, helpful compiler errors, and functional programming.
85 Covers both full applications and one-off scripts.
86- [writing-rust](skills/writing-rust/SKILL.md): Write idiomatic Rust with strict
87 quality gates: `cargo fmt`, `clippy -- -D warnings`, and required tests.
88 Enforces `thiserror` for libs, `anyhow` for apps, warns against common
89 anti-patterns.
90
91[blader/humanizer]: https://github.com/blader/humanizer
92[ast-grep]: https://github.com/ast-grep/ast-grep
93[git-format]: https://git.secluded.site/git-format
94[lune]: https://git.secluded.site/lune
95[Lunatask]: https://lunatask.app/
96[rumilo]: https://git.secluded.site/rumilo
97[synu]: https://git.secluded.site/synu
98[wt]: https://git.secluded.site/wt
99[gum]: https://github.com/charmbracelet/gum
100
101## Installation
102
103If you're using [Amp], run `amp skill add
104https://git.secluded.site/agent-skills`. Otherwise, clone the repository, then
105install via `make` or manual symlinks.
106
107[Amp]: https://ampcode.com
108
109```sh
110git clone https://git.secluded.site/agent-skills
111cd agent-skills
112```
113
114### With Make
115
116Skills install to `~/.config/agents/skills/` by default. Override by
117setting `SKILL_DIR`. Tab completion works so you don't have to remember
118skill names or copy/paste.
119
120```sh
121# List available skills
122make list
123
124# Install all skills to default dir
125make all
126
127# Install specific skills to Claude Code
128SKILL_DIR=$HOME/.claude/skills make authoring-skills formatting-commits
129
130# Remove a specific skill from Amp
131make uninstall-authoring-skills SKILL_DIR=$HOME/.config/agents/skills
132
133# Remove all skills from Codex
134make uninstall SKILL_DIR=$HOME/.codex/skills
135```
136
137### With symlinks
138
139```sh
140# Install all skills
141for s in skills/*/; do ln -s "$PWD/$s" ~/.config/agents/skills/; done
142
143# Install specific skills
144ln -s "$PWD/skills/authoring-skills" ~/.config/agents/skills/
145
146# Remove a skill
147rm ~/.config/agents/skills/formatting-commits
148```
149
150### Agent skill directories
151
152| Agent | Dir |
153| --------------------------------------- | -------------------------- |
154| [Crush], [Octofriend], [Shelley], [Amp] | `~/.config/agents/skills/` |
155| [Pi] | `~/.pi/agent/skills/` |
156| Anthropic's Claude Code | `~/.claude/skills/` |
157| OpenAI's Codex | `~/.codex/skills/` |
158
159## Updating
160
161```sh
162cd ~/path/to/agent-skills
163git pull
164```
165
166Symlinked skills update automatically.
167
168## Contributions
169
170Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't
171need a new account to contribute, you don't need to fork this repo, you
172don't need to fiddle with `git send-email`, you don't need to faff with
173your email client to get `git request-pull` working...
174
175You just need:
176
177- Git
178- SSH
179- An SSH key
180
181```sh
182# Clone this repo, make your changes, and commit them
183# Create a new patch request with
184git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
185# After potential feedback, submit a revision to an existing patch request with
186git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
187# List patch requests
188ssh pr.pico.sh pr ls amolith/llm-projects
189```
190
191See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
192complete example workflow.
193
194[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
195[pr.pico.sh]: https://pr.pico.sh
196
197## Token stats
198
199Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens] endpoint with [./skill-stats.go](./skill-stats.go).
200
201[Synthetic.new]: https://synthetic.new
202[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens
203
204```
205=== addressing-agent-comments ===
206
207Token breakdown:
208 Name: 22 tokens
209 Description: 96 tokens
210 Body: 706 tokens (40 lines)
211 ───────────────────────────────────────────────
212 Total: 824 tokens
213
214=== ast-grep ===
215
216Token breakdown:
217 Name: 18 tokens
218 Description: 198 tokens
219 Body: 7503 tokens (469 lines)
220 References:
221 rule_reference.md 6814 tokens
222 ───────────────────────────────────────────────
223 Total: 14533 tokens
224 ⚠️ Body exceeds recommended 5000 token budget!
225
226=== authoring-skills ===
227
228Token breakdown:
229 Name: 20 tokens
230 Description: 86 tokens
231 Body: 2000 tokens (102 lines)
232 References:
233 checklist.md 806 tokens
234 patterns.md 2415 tokens
235 process.md 833 tokens
236 specification.md 3890 tokens
237 ───────────────────────────────────────────────
238 Total: 10050 tokens
239
240=== creating-tasks-through-lunatask ===
241
242Token breakdown:
243 Name: 30 tokens
244 Description: 108 tokens
245 Body: 1927 tokens (88 lines)
246 References:
247 cli.md 589 tokens
248 handoff.md 2769 tokens
249 installing-lune.md 176 tokens
250 ───────────────────────────────────────────────
251 Total: 5599 tokens
252
253=== formatting-commits ===
254
255Token breakdown:
256 Name: 22 tokens
257 Description: 98 tokens
258 Body: 992 tokens (43 lines)
259 References:
260 installing-git-format.md 64 tokens
261 ───────────────────────────────────────────────
262 Total: 1176 tokens
263
264=== frontend-accessibility ===
265
266Token breakdown:
267 Name: 20 tokens
268 Description: 140 tokens
269 Body: 2891 tokens (148 lines)
270 References:
271 antipatterns.md 3638 tokens
272 patterns.md 6233 tokens
273 ───────────────────────────────────────────────
274 Total: 12922 tokens
275
276=== handling-customer-data ===
277
278Token breakdown:
279 Name: 22 tokens
280 Description: 123 tokens
281 Body: 1983 tokens (107 lines)
282 ───────────────────────────────────────────────
283 Total: 2128 tokens
284
285=== humanizer ===
286
287Token breakdown:
288 Name: 15 tokens
289 Description: 84 tokens
290 Body: 8536 tokens (462 lines)
291 ───────────────────────────────────────────────
292 Total: 8635 tokens
293 ⚠️ Body exceeds recommended 5000 token budget!
294
295=== invoking-subagents ===
296
297Token breakdown:
298 Name: 20 tokens
299 Description: 113 tokens
300 Body: 796 tokens (13 lines)
301 References:
302 installing-synu.md 140 tokens
303 ───────────────────────────────────────────────
304 Total: 1069 tokens
305
306=== managing-and-navigating-worktrees ===
307
308Token breakdown:
309 Name: 32 tokens
310 Description: 164 tokens
311 Body: 1912 tokens (96 lines)
312 ───────────────────────────────────────────────
313 Total: 2108 tokens
314
315=== querying-documentation ===
316
317Token breakdown:
318 Name: 22 tokens
319 Description: 132 tokens
320 Body: 796 tokens (22 lines)
321 References:
322 dependencies.md 108 tokens
323 ───────────────────────────────────────────────
324 Total: 1058 tokens
325
326=== rebasing-with-git ===
327
328Token breakdown:
329 Name: 22 tokens
330 Description: 188 tokens
331 Body: 5696 tokens (202 lines)
332 ───────────────────────────────────────────────
333 Total: 5906 tokens
334 ⚠️ Body exceeds recommended 5000 token budget!
335
336=== researching-with-rumilo ===
337
338Token breakdown:
339 Name: 25 tokens
340 Description: 159 tokens
341 Body: 1319 tokens (49 lines)
342 ───────────────────────────────────────────────
343 Total: 1503 tokens
344
345=== resuming-work-through-lunatask ===
346
347Token breakdown:
348 Name: 30 tokens
349 Description: 113 tokens
350 Body: 1241 tokens (42 lines)
351 References:
352 cli.md 528 tokens
353 installing-lune.md 176 tokens
354 ───────────────────────────────────────────────
355 Total: 2088 tokens
356
357=== reviewing-code ===
358
359Token breakdown:
360 Name: 18 tokens
361 Description: 125 tokens
362 Body: 1880 tokens (121 lines)
363 ───────────────────────────────────────────────
364 Total: 2023 tokens
365
366=== scripting-with-go ===
367
368Token breakdown:
369 Name: 20 tokens
370 Description: 120 tokens
371 Body: 1968 tokens (138 lines)
372 ───────────────────────────────────────────────
373 Total: 2108 tokens
374
375=== working-with-tmux ===
376
377Token breakdown:
378 Name: 22 tokens
379 Description: 84 tokens
380 Body: 1465 tokens (87 lines)
381 ───────────────────────────────────────────────
382 Total: 1571 tokens
383
384=== writing-git-tags ===
385
386Token breakdown:
387 Name: 22 tokens
388 Description: 101 tokens
389 Body: 2232 tokens (107 lines)
390 References:
391 installing-git-format.md 64 tokens
392 ───────────────────────────────────────────────
393 Total: 2419 tokens
394
395=== writing-roc-lang ===
396
397Token breakdown:
398 Name: 22 tokens
399 Description: 142 tokens
400 Body: 1846 tokens (117 lines)
401 References:
402 builtins-llms.md 67881 tokens
403 llms.md 11324 tokens
404 scripting.md 1722 tokens
405 ───────────────────────────────────────────────
406 Total: 82937 tokens
407
408=== writing-rust ===
409
410Token breakdown:
411 Name: 18 tokens
412 Description: 120 tokens
413 Body: 3628 tokens (139 lines)
414 References:
415 idioms.md 4605 tokens
416 ───────────────────────────────────────────────
417 Total: 8371 tokens
418
419============================================================
420SUMMARY
421============================================================
422
423Skills: 20
424Metadata: 2936 tokens
425Combined bodies: 51317 tokens
426Overall: 169028 tokens
427Validation errors: 0
428
429Largest skills (by total tokens):
430 1. writing-roc-lang 82937 tokens
431 2. ast-grep 14533 tokens
432 3. frontend-accessibility 12922 tokens
433 4. authoring-skills 10050 tokens
434 5. humanizer 8635 tokens
435```
436
437---
438
439Some other tools if these interested you
440
441- [wt](https://git.secluded.site/wt) - CLI for managing git worktrees
442- [git-format](https://git.secluded.site/git-format) - CLI that turns LLM input
443 into well-formatted conventional commits and tags
444- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix
445 typos, translate, reformat)
446- [lune](https://git.secluded.site/lune) - CLI and MCP server for
447 [Lunatask.app](https://lunatask.app)