<!--
SPDX-FileCopyrightText: Amolith <amolith@secluded.site>

SPDX-License-Identifier: CC0-1.0
-->

# agent-skills

A collection of [Agent Skills]; structured markdown that extends LLM
agent capabilities through a standardised format.

[Agent Skills]: https://agentskills.io/

## Available Skills

Refer to [§ Token stats](#token-stats) for a detailed breakdown of each skill's
token count, plus overall metadata usage. I've used and tested them most with
[Crush], [Amp], and [Shelley], and to a lesser degree, [Octofriend] and [Pi].

[Crush]: https://github.com/charmbracelet/crush
[Amp]: https://ampcode.com
[Shelley]: https://github.com/boldsoftware/shelley
[Octofriend]: https://github.com/synthetic-lab/octofriend
[Pi]: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent

- [addressing-agent-comments](skills/addressing-agent-comments/SKILL.md): Finds
  `AGENT:` comments in code, gathers feedback, and carries out requested
  changes.
- [ast-grep](skills/ast-grep/SKILL.md): Writes [ast-grep] rules for structural
  code search and modification.
- [auditing-repositories](skills/auditing-repositories/SKILL.md): Audits open
  source repositories for security, privacy, and unexpected behavior.
- [authoring-skills](skills/authoring-skills/SKILL.md): Creates and reviews
  Agent Skills following best practices. Covers skill structure, frontmatter,
  and progressive disclosure patterns.
- [collaborating-through-pr-pico-sh](skills/collaborating-through-pr-pico-sh/SKILL.md):
  Collaborates on git patches via [pr.pico.sh], a minimal patchbin service.
  Covers both contributing and reviewing patch requests using `git format-patch`
  and `git am`.
- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
  Creates tasks and handoffs in [Lunatask] via [lune]. Tasks are just tasks.
  Handoffs capture work to resume later across sessions without filling context
  windows.
- [formatting-commits](skills/formatting-commits/SKILL.md): Creates commits
  following Conventional Commits format via [git-format].
- [frontend-accessibility](skills/frontend-accessibility/SKILL.md): Strives to
  generate accessible HTML, React, and frontend code following WCAG 2.2 AA.
  Prioritizes semantic HTML over ARIA, keyboard navigation, and screen reader
  compatibility.
- [handling-customer-data](skills/handling-customer-data/SKILL.md): Queries
  customer data responsibly—the agent answers questions about the data without
  ever seeing it directly.
- [humanizer](skills/humanizer/SKILL.md): Removes AI-generated patterns from
  text like promotional fluff, weasel words, and mechanical sentence structures.
  Based on Wikipedia's AI Cleanup research. Originally from [blader/humanizer].
- [invoking-subagents](skills/invoking-subagents/SKILL.md): Spawns subagents
  with restricted tool access for parallel tasks across repositories. Requires
  [synu] and the `claude` CLI. Useful for summarizing git history or processing
  large diffs without filling the main context window.
- [managing-and-navigating-worktrees](skills/managing-and-navigating-worktrees/SKILL.md):
  Manages git worktrees using [wt] with a bare repository structure. Each branch
  lives in its own sibling directory. Requires [wt], git, and [gum].
- [notifying-through-ntfy](skills/notifying-through-ntfy/SKILL.md): Sends push
  notifications via [ntfy.sh] when requested, such as at the end of its turn.
- [rebasing-with-git](skills/rebasing-with-git/SKILL.md): Manages git rebase
  workflows from simple rebases to the drop-and-repick integration branch
  pattern. Assumes `upstream` remote for forks and `rerere` enabled. Supports
  worktrees including `wt`-managed repos.
- [researching-with-rumilo](skills/researching-with-rumilo/SKILL.md): Dispatches
  AI research subagents via [rumilo] for web search and repository exploration.
  Research topics, look up library usage, or explore external codebases without
  filling the main context window.
- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
  Resumes deferred work from [Lunatask] handoff notes via [lune].
- [reviewing-code](skills/reviewing-code/SKILL.md): Reviews changes, commits,
  PRs, and patches using Kodus, CodeRabbit, or Amp, preferring whichever is
  available in that order.
- [scripting-with-go](skills/scripting-with-go/SKILL.md): Creates executable Go
  scripts using a shell trick (not a true shebang). For automation and tooling
  outside of Go projects.
- [working-with-tmux](skills/working-with-tmux/SKILL.md): Spawns and manages
  background processes via tmux. Creates windows, sends commands, and captures
  output without blocking the main session. Useful for servers and long tasks.
- [writing-git-tags](skills/writing-git-tags/SKILL.md): Generates git tag
  annotations from commit history following Semantic Versioning and Conventional
  Commits via [git-format].
- [writing-roc-lang](skills/writing-roc-lang/SKILL.md): Writes Roc code with
  strong static types, helpful compiler errors, and functional programming.
  Covers both full applications and one-off scripts.
- [writing-rust](skills/writing-rust/SKILL.md): Writes idiomatic Rust with
  strict quality gates: `cargo fmt`, `clippy -- -D warnings`, and required
  tests. Enforces `thiserror` for libs, `anyhow` for apps, warns against common
  anti-patterns.

[blader/humanizer]: https://github.com/blader/humanizer
[ast-grep]: https://github.com/ast-grep/ast-grep
[git-format]: https://git.secluded.site/git-format
[lune]: https://git.secluded.site/lune
[Lunatask]: https://lunatask.app/
[ntfy.sh]: https://ntfy.sh
[rumilo]: https://git.secluded.site/rumilo
[synu]: https://git.secluded.site/synu
[wt]: https://git.secluded.site/wt
[gum]: https://github.com/charmbracelet/gum

## Installation

If you're using [Amp], run `amp skill add
https://git.secluded.site/agent-skills`. Otherwise, clone the repository, then
install via `make` or manual symlinks.

[Amp]: https://ampcode.com

```sh
git clone https://git.secluded.site/agent-skills
cd agent-skills
```

### With Make

Skills install to `~/.config/agents/skills/` by default. Override by
setting `SKILL_DIR`. Tab completion works so you don't have to remember
skill names or copy/paste.

```sh
# List available skills
make list

# Install all skills to default dir
make all

# Install specific skills to Claude Code
SKILL_DIR=$HOME/.claude/skills make authoring-skills formatting-commits

# Remove a specific skill from Amp
make uninstall-authoring-skills SKILL_DIR=$HOME/.config/agents/skills

# Remove all skills from Codex
make uninstall SKILL_DIR=$HOME/.codex/skills
```

### With symlinks

```sh
# Install all skills
for s in skills/*/; do ln -s "$PWD/$s" ~/.config/agents/skills/; done

# Install specific skills
ln -s "$PWD/skills/authoring-skills" ~/.config/agents/skills/

# Remove a skill
rm ~/.config/agents/skills/formatting-commits
```

### Agent skill directories

| Agent                                   | Dir                        |
| --------------------------------------- | -------------------------- |
| [Crush], [Octofriend], [Shelley], [Amp] | `~/.config/agents/skills/` |
| [Pi]                                    | `~/.pi/agent/skills/`      |
| Anthropic's Claude Code                 | `~/.claude/skills/`        |
| OpenAI's Codex                          | `~/.codex/skills/`         |

## Updating

```sh
cd ~/path/to/agent-skills
git pull
```

Symlinked skills update automatically.

## Contributions

Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
new account to contribute, you don't need to fork this repo, you don't need to
fiddle with `git send-email`, you don't need to faff with your email client to
get `git request-pull` working...

You just need:

- Git
- SSH
- An SSH key

```sh
# Clone this repo, make your changes, and commit them
# Create a new patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
# After potential feedback, submit a revision to an existing patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
# List patch requests
ssh pr.pico.sh pr ls amolith/llm-projects
```

See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
complete example workflow.

[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
[pr.pico.sh]: https://pr.pico.sh

## Token stats

Real token stats as reported by [Synthetic.new]'s [/messages/count_tokens]
endpoint with [./skill-stats.go](./skill-stats.go).

[Synthetic.new]: https://synthetic.new
[/messages/count_tokens]: https://dev.synthetic.new/docs/anthropic/messages/count-tokens

```
=== addressing-agent-comments ===

Token breakdown:
  Name:           22 tokens
  Description:    96 tokens
  Body:          706 tokens (40 lines)
  ───────────────────────────────────────────────
  Total:         824 tokens

=== ast-grep ===

Token breakdown:
  Name:           18 tokens
  Description:   198 tokens
  Body:         7503 tokens (469 lines)
  References:
    rule_reference.md                         6814 tokens
  ───────────────────────────────────────────────
  Total:       14533 tokens
  ⚠️  Body exceeds recommended 5000 token budget!

=== auditing-repositories ===

Token breakdown:
  Name:           20 tokens
  Description:   140 tokens
  Body:         2840 tokens (156 lines)
  References:
    llm-security.md                           1138 tokens
  ───────────────────────────────────────────────
  Total:        4138 tokens

=== authoring-skills ===

Token breakdown:
  Name:           20 tokens
  Description:    86 tokens
  Body:         2000 tokens (102 lines)
  References:
    checklist.md                               806 tokens
    patterns.md                               2415 tokens
    process.md                                 833 tokens
    specification.md                          3890 tokens
  ───────────────────────────────────────────────
  Total:       10050 tokens

=== collaborating-through-pr-pico-sh ===

Token breakdown:
  Name:           30 tokens
  Description:   120 tokens
  Body:         1260 tokens (42 lines)
  References:
    contributing.md                            435 tokens
    reviewing.md                              1080 tokens
  ───────────────────────────────────────────────
  Total:        2925 tokens

=== creating-tasks-through-lunatask ===

Token breakdown:
  Name:           30 tokens
  Description:   108 tokens
  Body:         1841 tokens (84 lines)
  References:
    cli.md                                     589 tokens
    handoff.md                                2769 tokens
    installing-lune.md                         176 tokens
  ───────────────────────────────────────────────
  Total:        5513 tokens

=== formatting-commits ===

Token breakdown:
  Name:           22 tokens
  Description:    98 tokens
  Body:          992 tokens (43 lines)
  References:
    installing-git-format.md                    64 tokens
  ───────────────────────────────────────────────
  Total:        1176 tokens

=== frontend-accessibility ===

Token breakdown:
  Name:           20 tokens
  Description:   140 tokens
  Body:         2891 tokens (148 lines)
  References:
    antipatterns.md                           3638 tokens
    patterns.md                               6233 tokens
  ───────────────────────────────────────────────
  Total:       12922 tokens

=== handling-customer-data ===

Token breakdown:
  Name:           22 tokens
  Description:   123 tokens
  Body:         1983 tokens (107 lines)
  ───────────────────────────────────────────────
  Total:        2128 tokens

=== humanizer ===

Token breakdown:
  Name:           15 tokens
  Description:    84 tokens
  Body:         8536 tokens (462 lines)
  ───────────────────────────────────────────────
  Total:        8635 tokens
  ⚠️  Body exceeds recommended 5000 token budget!

=== invoking-subagents ===

Token breakdown:
  Name:           20 tokens
  Description:   113 tokens
  Body:          796 tokens (13 lines)
  References:
    installing-synu.md                         140 tokens
  ───────────────────────────────────────────────
  Total:        1069 tokens

=== managing-and-navigating-worktrees ===

Token breakdown:
  Name:           32 tokens
  Description:   164 tokens
  Body:         1912 tokens (96 lines)
  ───────────────────────────────────────────────
  Total:        2108 tokens

=== notifying-through-ntfy ===

Token breakdown:
  Name:           25 tokens
  Description:    93 tokens
  Body:         2884 tokens (89 lines)
  References:
    ht.md                                     1063 tokens
    httpie.md                                 1067 tokens
    nodejs.md                                 1497 tokens
    python.md                                 1468 tokens
    wget.md                                   1216 tokens
  ───────────────────────────────────────────────
  Total:        9313 tokens

=== rebasing-with-git ===

Token breakdown:
  Name:           22 tokens
  Description:   188 tokens
  Body:         6282 tokens (232 lines)
  ───────────────────────────────────────────────
  Total:        6492 tokens
  ⚠️  Body exceeds recommended 5000 token budget!

=== researching-with-rumilo ===

Token breakdown:
  Name:           25 tokens
  Description:   159 tokens
  Body:         3082 tokens (111 lines)
  ───────────────────────────────────────────────
  Total:        3266 tokens

=== resuming-work-through-lunatask ===

Token breakdown:
  Name:           30 tokens
  Description:   113 tokens
  Body:         1241 tokens (42 lines)
  References:
    cli.md                                     528 tokens
    installing-lune.md                         176 tokens
  ───────────────────────────────────────────────
  Total:        2088 tokens

=== reviewing-code ===

Token breakdown:
  Name:           18 tokens
  Description:   132 tokens
  Body:          970 tokens (48 lines)
  ───────────────────────────────────────────────
  Total:        1120 tokens

=== scripting-with-go ===

Token breakdown:
  Name:           20 tokens
  Description:   120 tokens
  Body:         1968 tokens (138 lines)
  ───────────────────────────────────────────────
  Total:        2108 tokens

=== working-with-tmux ===

Token breakdown:
  Name:           22 tokens
  Description:    84 tokens
  Body:         1465 tokens (87 lines)
  ───────────────────────────────────────────────
  Total:        1571 tokens

=== writing-git-tags ===

Token breakdown:
  Name:           22 tokens
  Description:   101 tokens
  Body:         2232 tokens (107 lines)
  References:
    installing-git-format.md                    64 tokens
  ───────────────────────────────────────────────
  Total:        2419 tokens

=== writing-roc-lang ===

Token breakdown:
  Name:           22 tokens
  Description:   142 tokens
  Body:         1846 tokens (117 lines)
  References:
    builtins-llms.md                         67881 tokens
    llms.md                                  11324 tokens
    scripting.md                              1722 tokens
  ───────────────────────────────────────────────
  Total:       82937 tokens

=== writing-rust ===

Token breakdown:
  Name:           18 tokens
  Description:   120 tokens
  Body:         3628 tokens (139 lines)
  References:
    idioms.md                                 4605 tokens
  ───────────────────────────────────────────────
  Total:        8371 tokens

============================================================
SUMMARY
============================================================

Skills: 22
Metadata: 3217 tokens
Combined bodies: 58858 tokens
Overall: 185706 tokens
Validation errors: 0

Largest skills (by total tokens):
  1. writing-roc-lang                         82937 tokens
  2. ast-grep                                 14533 tokens
  3. frontend-accessibility                   12922 tokens
  4. authoring-skills                         10050 tokens
  5. notifying-through-ntfy                    9313 tokens
```

---

Some other tools if these interested you

- [wt](https://git.secluded.site/wt) - CLI for managing git worktrees
- [git-format](https://git.secluded.site/git-format) - CLI that turns LLM input
  into well-formatted conventional commits and tags
- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix
  typos, translate, reformat)
- [lune](https://git.secluded.site/lune) - CLI and MCP server for
  [Lunatask.app](https://lunatask.app)