manage-skills

Files (1)

• SKILL.md

SKILL.md (first lines)

# Manage Skills

Create, update, and manage Claude Code skills (slash commands) across the two-layer dotfiles setup.

## Two-layer model

AI coding tool configs live in two repos:

- **Public layer** — `~/projects/clemens33/dotfiles/`
  - Remote: `git@github.com:clemens33/dotfiles.git`
  - Generic, shareable skills (planning, refactoring, security review, doctrine, etc.)
- **Private overlay** (optional submodule) — `~/projects/clemens33/dotfiles/dotfiles-mic/`
  - Remote: `git@github.com:clemens33/dotfiles-mic.git`
  - Org-specific skills + agents (jira, grafana, internal infra, credentials patterns)
  - Only fetched on machines with auth to the private repo

Both layers contribute skill symlinks into `~/.claude/skills/` (real directory, NOT a directory symlink — each skill is its own symlink). The wrapper `./install` script runs the public layer's Dotbot pass, then optionally runs the private overlay's Dotbot pass if the submodule is present.

## Decide which layer

| Skill characteristic | Layer |
|---|---|
| Generic engineering practice (TDD, refactoring, code review, scope, doctrine-shaped) | Public |
| References internal URLs, hostnames, project keys, or customer/product names | Private |
| Wraps an internal API or credential pattern | Private |
| Uses only standard tooling (git, ripgrep, generic CLI) | Public |
| Domain knowledge tied to a specific company/customer | Private |

When in doubt: start public. Move to private only if leak-checking surfaces internal content.

## Creating a new public skill

```bash
cd ~/projects/clemens33/dotfiles
mkdir -p skills/<skill-name>
$EDITOR skills/<skill-name>/SKILL.md
```

Start from the canonical template below — it is the only skill template in this repo, and it
is written to pass `lint-skills.sh` on the first run.

**Add a symlink entry in the public `install.conf.yaml`** for both Claude Code (`~/.claude/skills/<skill-name>: skills/<skill-name>`) and Codex (`~/.agents/skills/<skill-name>: skills/<skill-name>`). Codex user-scope skills live in `~/.agents/skills`; `~/.codex/skills` is legacy and holds Codex's own `.system` set.

Re-run install to pick up the new symlinks:

```bash
./install
```

Commit + push:

```bash
git add -- skills/<skill-name>/ install.conf.yaml
git commit -m "add <skill-name> skill"
git push
```

Stage the **skill directory**, not just `SKILL.md`: any `references/`, `scripts/` or `assets/`
you created alongside it would otherwise stay untracked, and the skill would land broken for
everyone else. Never `git add -A` — other lanes' work is in this checkout too.

## Creating a new private skill

```bash
cd ~/projects/clemens33/dotfiles/dotfiles-mic
mkdir -p skills/<skill-name>
$EDITOR skills/<skill-name>/SKILL.md
```

Same template as above. Add symlink entries in the **private overlay** `install.conf.yaml`. Re-run install from the public root:

```bash
cd ~/projects/clemens33/dotfiles
./install
```

Commit + push in the private repo first, then update the public submodule pointer:

```bash
cd dotfiles-mic
git add -- skills/<skill-name>/ install.conf.yaml
git commit -m "add <skill-name> skill"
git push
cd ..
git add dotfiles-mic
git commit -m "submodule: bump dotfiles-mic"
git push
```

## Canonical skill template

One template, both layers. Copy it verbatim and fill it in:

```markdown
---
name: my-skill
description: >
  What this skill does, front-loaded in the first clause. Use when <the
  concrete triggers — what the user says, or the situation that calls for it>.
  Not for <the nearest adjacent skill's job> — use `that-skill` instead.
metadata:
  category: capability

---

# Skill Title

One line on what this skill does.

## Configuration

API URLs, env vars, credentials paths. Private skills reference
`~/.config/<service>/credentials.env` and `$ENV_VAR` placeholders — never
inline secrets.

## Workflow

Step-by-step instructions with commands, API calls, code patterns.

From clemens33/dotfiles, MIT.

More from clemens33/dotfiles