<!--
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

- [authoring-skills](skills/authoring-skills/SKILL.md): Creates
  well-structured Agent Skills following best practices. Use when
  writing new skills, reviewing existing skills, or when the user
  mentions skill authoring.
- [formatting-commits](skills/formatting-commits/SKILL.md): Creates
  commits strictly following Conventional Commits format via the
  `formatted-commit` CLI.
- [invoking-subagents](skills/invoking-subagents/SKILL.md): Invokes
  ad-hoc subagents to read through lots of data and extract relevant
  information. Useful for exploring repositories, reading git logs,
  reviewing large diffs.
- [querying-documentation](skills/querying-documentation/SKILL.md):
  Spawns focused agents to search specific language/framework
  documentation and answer moderately complex queries.
- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
  Creates tasks in Lunatask for todos, reminders, deferred work, and
  handoffs.
- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
  Resumes previously deferred work from Lunatask. Use when user pastes a
  task note, shares a deep link, or references continuing earlier work.

## Installation

Clone the repository, then install skills via `make` or manual symlinks.

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

### With Make

Skills install to `~/.config/crush/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/crush/skills/; done

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

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

### Agent skill directories

| Agent                   | Dir                        |
| ----------------------- | -------------------------- |
| Crush                   | `~/.config/crush/skills/`  |
| Amp                     | `~/.config/agents/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