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- [authoring-skills](skills/authoring-skills/SKILL.md): Creates
19 well-structured Agent Skills following best practices. Use when
20 writing new skills, reviewing existing skills, or when the user
21 mentions skill authoring.
22- [formatting-commits](skills/formatting-commits/SKILL.md): Creates
23 commits strictly following Conventional Commits format via the
24 `formatted-commit` CLI.
25- [invoking-subagents](skills/invoking-subagents/SKILL.md): Invokes
26 ad-hoc subagents to read through lots of data and extract relevant
27 information. Useful for exploring repositories, reading git logs,
28 reviewing large diffs.
29- [querying-documentation](skills/querying-documentation/SKILL.md):
30 Spawns focused agents to search specific language/framework
31 documentation and answer moderately complex queries.
32- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
33 Creates tasks in Lunatask for todos, reminders, deferred work, and
34 handoffs.
35- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
36 Resumes previously deferred work from Lunatask. Use when user pastes a
37 task note, shares a deep link, or references continuing earlier work.
38- [frontend-accessibility](skills/frontend-accessibility/SKILL.md):
39 Generates accessible HTML, React, and frontend code following WCAG 2.2
40 AA guidelines. Focuses on semantic HTML, keyboard accessibility, and
41 screen reader compatibility.
42- [handling-customer-data](skills/handling-customer-data/SKILL.md):
43 Handles customer data responsibly by answering questions about data
44 without ever seeing the data directly.
45- [scripting-with-go](skills/scripting-with-go/SKILL.md): Creates
46 executable Go scripts with shebang-like behavior for long-lived
47 automation.
48- [writing-roc-lang](skills/writing-roc-lang/SKILL.md): Writes Roc code
49 with strong static types, helpful compiler errors, and functional
50 programming. Covers both full applications and one-off scripts.
51- [resolving-secrets](skills/resolving-secrets/SKILL.md): Wraps shell
52 commands to resolve secret references in environment variables.
53
54## Installation
55
56Clone the repository, then install skills via `make` or manual symlinks.
57
58```sh
59git clone https://git.secluded.site/agent-skills
60cd agent-skills
61```
62
63### With Make
64
65Skills install to `~/.config/crush/skills/` by default. Override by
66setting `SKILL_DIR`. Tab completion works so you don't have to remember
67skill names or copy/paste.
68
69```sh
70# List available skills
71make list
72
73# Install all skills to default dir
74make all
75
76# Install specific skills to Claude Code
77SKILL_DIR=$HOME/.claude/skills make authoring-skills formatting-commits
78
79# Remove a specific skill from Amp
80make uninstall-authoring-skills SKILL_DIR=$HOME/.config/agents/skills
81
82# Remove all skills from Codex
83make uninstall SKILL_DIR=$HOME/.codex/skills
84```
85
86### With symlinks
87
88```sh
89# Install all skills
90for s in skills/*/; do ln -s "$PWD/$s" ~/.config/crush/skills/; done
91
92# Install specific skills
93ln -s "$PWD/skills/authoring-skills" ~/.config/crush/skills/
94
95# Remove a skill
96rm ~/.config/crush/skills/formatting-commits
97```
98
99### Agent skill directories
100
101| Agent | Dir |
102| ----------------------- | -------------------------- |
103| Crush | `~/.config/crush/skills/` |
104| Amp | `~/.config/agents/skills/` |
105| Anthropic's Claude Code | `~/.claude/skills/` |
106| OpenAI's Codex | `~/.codex/skills/` |
107
108## Updating
109
110```sh
111cd ~/path/to/agent-skills
112git pull
113```
114
115Symlinked skills update automatically.
116
117## Contributions
118
119Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't
120need a new account to contribute, you don't need to fork this repo, you
121don't need to fiddle with `git send-email`, you don't need to faff with
122your email client to get `git request-pull` working...
123
124You just need:
125
126- Git
127- SSH
128- An SSH key
129
130```sh
131# Clone this repo, make your changes, and commit them
132# Create a new patch request with
133git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
134# After potential feedback, submit a revision to an existing patch request with
135git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
136# List patch requests
137ssh pr.pico.sh pr ls amolith/llm-projects
138```
139
140See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
141complete example workflow.
142
143[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
144[pr.pico.sh]: https://pr.pico.sh
145
146## Token stats
147
148Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens] endpoint with [./skill-stats.go](./skill-stats.go).
149
150[Synthetic.new]: https://synthetic.new
151[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens
152
153```
154=== authoring-skills ===
155
156Token breakdown:
157 Name: 20 tokens
158 Description: 86 tokens
159 Body: 2000 tokens (102 lines)
160 References:
161 checklist.md 806 tokens
162 patterns.md 2415 tokens
163 process.md 833 tokens
164 specification.md 3890 tokens
165 ───────────────────────────────────────────────
166 Total: 10050 tokens
167
168=== creating-tasks-through-lunatask ===
169
170Token breakdown:
171 Name: 30 tokens
172 Description: 108 tokens
173 Body: 1927 tokens (88 lines)
174 References:
175 cli.md 589 tokens
176 handoff.md 2769 tokens
177 installing-lune.md 176 tokens
178 ───────────────────────────────────────────────
179 Total: 5599 tokens
180
181=== formatting-commits ===
182
183Token breakdown:
184 Name: 22 tokens
185 Description: 98 tokens
186 Body: 796 tokens (38 lines)
187 References:
188 installing-formatted-commit.md 296 tokens
189 ───────────────────────────────────────────────
190 Total: 1212 tokens
191
192=== frontend-accessibility ===
193
194Token breakdown:
195 Name: 20 tokens
196 Description: 140 tokens
197 Body: 2891 tokens (148 lines)
198 References:
199 antipatterns.md 3638 tokens
200 patterns.md 6233 tokens
201 ───────────────────────────────────────────────
202 Total: 12922 tokens
203
204=== handling-customer-data ===
205
206Token breakdown:
207 Name: 22 tokens
208 Description: 123 tokens
209 Body: 1983 tokens (107 lines)
210 ───────────────────────────────────────────────
211 Total: 2128 tokens
212
213=== invoking-subagents ===
214
215Token breakdown:
216 Name: 20 tokens
217 Description: 113 tokens
218 Body: 796 tokens (13 lines)
219 References:
220 installing-synu.md 140 tokens
221 ───────────────────────────────────────────────
222 Total: 1069 tokens
223
224=== querying-documentation ===
225
226Token breakdown:
227 Name: 22 tokens
228 Description: 132 tokens
229 Body: 796 tokens (22 lines)
230 References:
231 dependencies.md 108 tokens
232 ───────────────────────────────────────────────
233 Total: 1058 tokens
234
235=== resolving-secrets ===
236
237Token breakdown:
238 Name: 20 tokens
239 Description: 120 tokens
240 Body: 259 tokens (10 lines)
241 References:
242 installing-opx.md 125 tokens
243 ───────────────────────────────────────────────
244 Total: 524 tokens
245
246=== resuming-work-through-lunatask ===
247
248Token breakdown:
249 Name: 30 tokens
250 Description: 113 tokens
251 Body: 1241 tokens (42 lines)
252 References:
253 cli.md 528 tokens
254 installing-lune.md 176 tokens
255 ───────────────────────────────────────────────
256 Total: 2088 tokens
257
258=== scripting-with-go ===
259
260Token breakdown:
261 Name: 20 tokens
262 Description: 120 tokens
263 Body: 1968 tokens (138 lines)
264 ───────────────────────────────────────────────
265 Total: 2108 tokens
266
267=== writing-roc-lang ===
268
269Token breakdown:
270 Name: 22 tokens
271 Description: 142 tokens
272 Body: 1846 tokens (117 lines)
273 References:
274 builtins-llms.md 67881 tokens
275 llms.md 11324 tokens
276 scripting.md 1722 tokens
277 ───────────────────────────────────────────────
278 Total: 82937 tokens
279
280============================================================
281SUMMARY
282============================================================
283
284Skills: 11
285Metadata: 1543 tokens
286Combined bodies: 16503 tokens
287Overall: 121695 tokens
288Validation errors: 0
289
290Largest skills (by total tokens):
291 1. writing-roc-lang 82937 tokens
292 2. frontend-accessibility 12922 tokens
293 3. authoring-skills 10050 tokens
294 4. creating-tasks-through-lunatask 5599 tokens
295 5. handling-customer-data 2128 tokens
296```