# opencode-skills

Reusable skills and commands for AI coding agents (OpenCode and Claude Code).

Skills follow the [Agent Skills](https://agentskills.io) open standard, so each `SKILL.md` works across both platforms.

## Contents

- `skills/<name>/SKILL.md` — agent skills, discovered on demand.
- `commands/*.md` — slash commands.

## Featured skill: `setup-context-system`

Guides a person through building a **layered context system** for their agent — global/project/initiative context files, index files, knowledge management (Rules/Hypotheses), decision logging, tone rules, an optional discovery methodology, and a maintenance command that keeps it all current. It teaches the pattern and interviews the user for their own content; the result is their system, not a copy.

It runs in phases (essentials first), gating after each so a user can stop with a working system at any point. Its final phase optionally offers to install [Superpowers](https://github.com/obra/superpowers) — obra's skills library that adds an automatic spec → plan → TDD workflow — as a process companion to this context layer.

## Installing a skill

A skill is a self-contained `SKILL.md`. Both platforms read skills from specific config directories — putting the file in those directories (or symlinking it there) is all that's required.

### Method 1 — Git clone + symlink (recommended, no drift)

Clone once, then symlink the skill into your agent's skills directory. Edits in the repo propagate automatically.

```bash
git clone https://git.aileverte.be/sampson/opencode-skills.git
cd opencode-skills

# OpenCode (global)
ln -s "$PWD/skills/setup-context-system" ~/.config/opencode/skills/setup-context-system

# Claude Code (global)
ln -s "$PWD/skills/setup-context-system" ~/.claude/skills/setup-context-system
```

Then run it: type `/setup-context-system`, or just describe the task and let the agent invoke it.

> Paths are verified against the official docs:
> - OpenCode reads `~/.config/opencode/skills/<name>/SKILL.md` (https://opencode.ai/docs/skills).
> - Claude Code reads `~/.claude/skills/<name>/SKILL.md` (https://docs.claude.com/en/docs/claude-code/skills).

### Method 2 — Agent install from the raw file (no clone)

If you don't want to clone, have your agent fetch the raw `SKILL.md` and drop it into your skills directory. Tell the agent:

> Fetch `https://git.aileverte.be/sampson/opencode-skills/raw/branch/master/skills/setup-context-system/SKILL.md`, save it to `~/.claude/skills/setup-context-system/SKILL.md` (or `~/.config/opencode/skills/setup-context-system/SKILL.md`), then run the `setup-context-system` skill.

Or do it manually:

```bash
# Claude Code
mkdir -p ~/.claude/skills/setup-context-system
curl -fsSL "https://git.aileverte.be/sampson/opencode-skills/raw/branch/master/skills/setup-context-system/SKILL.md" \
  -o ~/.claude/skills/setup-context-system/SKILL.md

# OpenCode
mkdir -p ~/.config/opencode/skills/setup-context-system
curl -fsSL "https://git.aileverte.be/sampson/opencode-skills/raw/branch/master/skills/setup-context-system/SKILL.md" \
  -o ~/.config/opencode/skills/setup-context-system/SKILL.md
```

> Method 2 copies the file, so it won't pick up repo updates automatically. Method 1 (symlink) avoids drift.

## Project-scoped install

To make a skill available only inside one project instead of globally, place it under that project's config dir instead:

- OpenCode: `.opencode/skills/<name>/SKILL.md`
- Claude Code: `.claude/skills/<name>/SKILL.md`