From d2f402043f23031695faca7423d727393b8bbb70 Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Sat, 27 Dec 2025 23:12:28 -0700
Subject: [PATCH] docs(readme): add

---
 README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..f0f0fbaede65831147fce64e6e678b205aad6e79
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+<!--
+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](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](formatting-commits/SKILL.md): Creates commits
+  strictly following Conventional Commits format via the
+  `formatted-commit` CLI.
+
+- [invoking-subagents](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](querying-documentation/SKILL.md): Spawns
+  focused agents to search specific language/framework documentation and
+  answer moderately complex queries.
+
+- [resolving-secrets](resolving-secrets/SKILL.md): Wraps shell commands
+  to resolve secret references in environment variables. Use when
+  invoking `synu`, `crush`, `gh`, `hut`, etc.
+
+## Installation
+
+Clone the repository, then symlink the skills you want into your agent's
+skills directory.
+
+```sh
+git clone https://git.secluded.site/agent-skills
+cd agent-skills
+```
+
+### With GNU Stow
+
+Get it from your preferred/available package manager (definitely true on
+Linux, I assume so on macOS and Windows)
+
+```sh
+# Install specific skills
+stow -t ~/.config/crush/skills authoring-skills formatting-commits
+
+# Remove a skill
+stow -D -t ~/.config/crush/skills formatting-commits
+```
+
+### With symlinks
+
+```sh
+# Install specific skills
+ln -s "$PWD/authoring-skills" ~/.config/crush/skills/
+ln -s "$PWD/formatting-commits" ~/.config/crush/skills/
+
+# Remove a skill
+rm ~/.config/crush/skills/formatting-commits
+```
+
+### Agent skill directories
+
+| Agent                   | Dir                       |
+| ----------------------- | ------------------------- |
+| Crush                   | `~/.config/crush/skills/` |
+| Amp                     | `~/.amp/skills/`          |
+| Anthropic's Claude Code | `~/.claude/skills/`       |
+| OpenAI's Codex          | `~/.codex/skills/`        |
+
+## Updating
+
+```sh
+cd ~/path/to/agent-skills
+git pull
+```
+
+Symlinked skills, either with stow or regular symlinks, 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