b1ff71a7fd
Some checks failed
release / tag (push) Has been cancelled
Phase 2 of mathias/skills extraction. Adds two new per-tool wirers alongside Claude Code: - Crush — ~/.config/crush/skills/<name>/SKILL.md (charmbracelet/crush, successor to opencode-ai/opencode which is archived) - Antigravity — ~/.gemini/antigravity/skills/<name>/SKILL.md (Google VS Code extension). Our SKILL.md frontmatter (name + description) is already in the format Antigravity expects — no manifest translation step needed. Both wirers added to Taskfile.yml (install:crush + install:antigravity) and install.sh (wire_crush + wire_antigravity). The aggregate `install` target now calls all four targets (claude:global, claude:repo, crush, antigravity). Idempotent symlinks, same shape as the Claude Code wirer. Per-host env overrides documented in README: SKILLS_REF for tag pinning, CRUSH_SKILLS_DIR + ANTIGRAVITY_SKILLS_DIR for non-default paths. Skipped: - opencode (opencode-ai/opencode): archived, succeeded by Crush; its Custom Commands surface is user prompt templates, not system skills - gitea-resident agents: consume via per-repo .claude/skills or brain MCP, no special target needed Bump-Type: minor
104 lines
4.2 KiB
Markdown
104 lines
4.2 KiB
Markdown
# skills
|
|
|
|
Engineering skills library — markdown `SKILL.md` files that plug into any
|
|
project or AI-coding harness. Installed via `task skills:install` in
|
|
consumer projects, or directly by `install.sh` on hosts without Task.
|
|
|
|
## What is a skill?
|
|
|
|
A skill is a single directory containing one or more markdown files. The
|
|
canonical entrypoint is `<name>/SKILL.md`. Additional reference material
|
|
lives alongside in the same directory (e.g.
|
|
`clean-code/references/code-smells.md`). Harnesses load skills on
|
|
demand — keep `SKILL.md` short and triggerable; push depth into
|
|
references.
|
|
|
|
See [`SKILLS_INDEX.md`](./SKILLS_INDEX.md) for the full catalogue with
|
|
descriptions and "use when" triggers.
|
|
|
|
## Install (consumer project)
|
|
|
|
The expected pattern: each consumer project's `Taskfile.yml` has a
|
|
`skills:install` target that delegates here. From a project root:
|
|
|
|
```bash
|
|
task skills:install
|
|
```
|
|
|
|
Bare-shell fallback for hosts without Task installed:
|
|
|
|
```bash
|
|
curl -fsSL https://gitea.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
|
|
```
|
|
|
|
Both forms are idempotent and re-runnable. On every run they:
|
|
|
|
1. `git clone` (or `git pull`) this repo into `~/.local/share/skills/` —
|
|
the **canonical local checkout** on every host.
|
|
2. Wire per-skill symlinks into the harnesses found on the host (see
|
|
[Wired harnesses](#wired-harnesses)).
|
|
|
|
Re-run after `git pull` upstream to pick up new skills or version
|
|
changes. CI tags every change as a `vX.Y.Z` release (see
|
|
[Versioning](#versioning)).
|
|
|
|
## Wired harnesses
|
|
|
|
| Harness | Target path | Notes |
|
|
|---|---|---|
|
|
| **Claude Code (global)** | `~/.claude/skills/<name>` | Visible in every Claude Code session on the host. |
|
|
| **Claude Code (per-repo)** | `<repo>/.claude/skills/<name>` | Created when `install` is invoked inside a git repo (not the skills repo itself). Gitignored globally via `**/.claude/skills/`. |
|
|
| **Crush** | `~/.config/crush/skills/<name>` | Charmbracelet Crush — successor to `opencode-ai/opencode` (archived). |
|
|
| **Antigravity** | `~/.gemini/antigravity/skills/<name>` | Google Antigravity (VS Code extension). Our `SKILL.md` frontmatter (`name` + `description`) is already in the format Antigravity expects, so symlinks suffice — no manifest translation. |
|
|
|
|
### Not wired (and why)
|
|
|
|
- **opencode** (`opencode-ai/opencode`): archive notice; succeeded by Crush.
|
|
Its only "skill"-like surface — Custom Commands at `~/.config/opencode/commands/` —
|
|
is for user-facing prompt templates, not system-level instructions.
|
|
Misaligned with how we use skills. Skipped.
|
|
- **gitea-resident agents** (cobalt-dingo, agentsquad): they consume
|
|
skills via their containing project's `.claude/skills` directory
|
|
(populated by the per-repo wirer when run from the host), or via the
|
|
brain MCP. No special target needed.
|
|
|
|
### Per-host env-var overrides
|
|
|
|
Each target path can be overridden by setting the matching env var before
|
|
running `install.sh`:
|
|
|
|
| Env var | Default |
|
|
|---|---|
|
|
| `SKILLS_REPO_URL` | `https://gitea.d-ma.be/mathias/skills.git` |
|
|
| `SKILLS_REF` | `main` (set to e.g. `v0.1.0` to pin a release) |
|
|
| `SKILLS_CHECKOUT_DIR` | `$HOME/.local/share/skills` |
|
|
| `CLAUDE_SKILLS_DIR` | `$HOME/.claude/skills` |
|
|
| `CRUSH_SKILLS_DIR` | `$HOME/.config/crush/skills` |
|
|
| `ANTIGRAVITY_SKILLS_DIR` | `$HOME/.gemini/antigravity/skills` |
|
|
|
|
## Versioning
|
|
|
|
Every commit to `main` is auto-tagged as a semver release by the
|
|
`.gitea/workflows/release.yml` action. Bump direction follows the commit
|
|
footer:
|
|
|
|
- `Bump-Type: major` → `X.0.0`
|
|
- `Bump-Type: minor` → `0.Y.0`
|
|
- *anything else* → `0.0.Z` (patch, the default)
|
|
|
|
Consumer projects can pin a version by setting `SKILLS_REF=v0.1.0`
|
|
before `task skills:install`; default is `main` for always-current.
|
|
|
|
## Contributing a skill
|
|
|
|
1. Add a directory `<short-kebab-name>/`.
|
|
2. Create `<short-kebab-name>/SKILL.md` — start with one-paragraph
|
|
purpose, then triggers ("use when …"), then mechanics.
|
|
3. Add a row to `SKILLS_INDEX.md` (description + use-when).
|
|
4. Commit directly to `main`. Conventional-commit prefix
|
|
(`feat:` / `fix:` / `docs:`). Add `Bump-Type: minor` footer when
|
|
adding a new skill or expanding scope; default patch covers edits.
|
|
|
|
This repo is markdown-only and public — never include secrets, client
|
|
names, or anything under NDA in a skill.
|