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