---
title: Repo Layout & Skill Workflow
type: concept
updated: 2026-04-28
---

# Repo Layout & Skill Workflow

_Decision: 2026-04-28. Approved by Vitya in chat._

## Goal

Single-source workshop for personal Claude skills. Edit here, build `.skill` archives here, install to `~/.claude/skills/` here. Repo must roll out cleanly to multiple machines.

## Layout

```
claude-skills/
├── skills/                  ← editable sources (source of truth)
│   ├── caveman/
│   ├── caveman-commit/
│   ├── caveman-compress/
│   ├── caveman-help/
│   ├── caveman-review/
│   ├── compress/
│   ├── find-skills/
│   ├── project-bootstrap/
│   ├── task-status-wiki/
│   ├── using-context7/
│   ├── using-markitdown/
│   └── wiki-maintainer/
├── dist/                    ← built .skill archives (committed)
├── scripts/
│   ├── build.sh             ← skills/<name>/ → dist/<name>.skill
│   └── install.sh           ← skills/<name>/ → ~/.claude/skills/<name>/
├── .wiki/, .tasks/, CLAUDE.md, README.md, .gitignore
```

## Build & Install Model

- **Source of truth:** `skills/<name>/` — a regular folder with `SKILL.md` + optional `assets/`, `references/`, etc. Mirrors the on-disk format Claude expects in `~/.claude/skills/`.
- **Build:** `scripts/build.sh [name...]` zips each `skills/<name>/` into `dist/<name>.skill`. No args → builds all.
- **Install:** `scripts/install.sh [name...]` copies (not symlinks) each `skills/<name>/` into `~/.claude/skills/<name>/`, replacing any existing folder. No args → installs all.
- **`.skill` archives are committed** to `dist/`. New machine: clone → run `install.sh` and you're set. No build dependency on the install path.
- **Cross-platform:** scripts are bash (works in git-bash on Windows + native on Linux/Mac). PowerShell variant added if/when needed.

## Conventions

- One folder per skill, name = skill name.
- Skill content authority: this repo. `~/.claude/skills/` is downstream.
- `dist/*.skill` regenerated by build script — never edited by hand.
- Editing flow: edit `skills/<name>/`, run `install.sh <name>` to push to live, run `build.sh <name>` to refresh archive, commit.

## Out of scope (for now)

- Versioning of individual skills (no `version` field, no changelog per skill).
- Manifest/registry file — flat folder is enough at 12 skills; revisit at ~30+.
- CI / automated builds — manual-only.
- Plugin skills (superpowers, frontend-design, etc.) — managed by plugin system, not mirrored here.