# askill - Universal AI Agent Skill Manager for Omarchy
askill installs AI-agent "skills" (the `SKILL.md` packages coding agents use) into one canonical vault, then symlinks every agent harness to it. A single skill works across Claude, Codex, opencode, Pi, Cursor and Windsurf without copying anything by hand.
## Why it exists
Each coding agent keeps skills in its own directory, named differently every time:
```
~/.claude/skills ~/.codex/skills ~/.opencode/skills
~/.pi/skills ~/.cursor/skills ~/.windsurf/skills
```
Installing the same skill into six places is slow and error-prone. askill keeps one copy and symlinks each agent dir to it:
```
~/.agents/skills/ <- the one real copy, every agent points here
^ symlinked out to each agent path
```
## Install
askill is one bash script. Any install method works.
### 1. Copy it to your PATH (recommended)
```bash
install -m 0755 askill ~/.local/bin/askill
```
If `~/.local/bin` isn't on your `PATH`, add `export PATH="$HOME/.local/bin:$PATH"` to your shell profile.
### 2. System-wide
```bash
sudo install -m 0755 askill /usr/local/bin/askill
```
### 3. Just try it
```bash
chmod +x ./askill
./askill --help
```
## Usage
```bash
askill add <git-url> # Fetch skills from a GitHub repo (validates SKILL.md)
askill sync # Re-bind missing or outdated agent harness links
askill list # List skills in the vault
askill remove <skill> # Remove a skill and clean its owned config dirs
askill tldr # Quick command examples
askill --help # Full help
```
Typical flow, install then confirm:
```bash
askill add https://github.com/username/awesome-skills
askill sync
askill list
```
## Removing a skill and cleaning up its files
`askill remove <skill>` prints every path it will delete, the skill directory and any config or data dirs the skill owns, then asks for a `[y/N]` confirmation before touching anything.
A skill can opt into cleanup by shipping a `purge.json` listing its owned paths, one per line, `~` expands to `$HOME`:
```json
~/.config/last30days
~/Documents/Last30Days
```
On remove, askill deletes only what `purge.json` lists. It never scrapes paths from `SKILL.md` prose. Those are often system configs like Hyprland or git that the skill only touches, and deleting them would be destructive. Missing paths are skipped with a notice. A skill with no `purge.json` leaves only its directory behind.
## Safety
- **Temp cleanup.** Downloads stage in a temp dir that's removed on every exit, including a failed clone, so nothing lingers in `/tmp`.
- **Safer sync.** `sync` only creates symlinks. It never copies over or deletes a real directory. If a harness path is a genuine folder instead of a symlink, it's left alone and reported.
- **Collision skip.** `add` won't silently overwrite a same-named skill that's already installed. It warns and tells you to remove it first.
- **Remove confirmation.** `remove` lists every file to be purged and asks yes or no before deleting, so a mistyped name can't destroy work.
## Help
```bash
askill --help # full usage and command list
askill tldr # quick example cheatsheet
```
## Disclaimer
askill was written for the author's private use, on an Omarchy Linux system. It depends on Omarchy and agent directory conventions and a Bash environment. It may not work, or may behave unpredictably, on other distributions or non-Omarchy setups. Use at your own risk. Read the script before running it, and back up your agent skill directories first.
Download link: askill