vitya
9f54068de0
- skills/: editable sources for all 12 personal skills (caveman family, find-skills, project-bootstrap, task-status-wiki, using-context7, using-markitdown, wiki-maintainer, compress) - dist/: built .skill archives, committed (cross-machine deploy without needing zip on the target) - scripts/build.sh + build.ps1: zip skills/<name>/ into dist/<name>.skill; Windows fallback uses .NET ZipArchive (PS 5.1 Compress-Archive writes backslashes that break extraction on *nix) - scripts/install.sh: copy skills/<name>/ into ~/.claude/skills/<name>/ ($CLAUDE_SKILLS_DIR overrides target) - .wiki/source/repo-layout.md, build-notes.md: design + gotchas - .gitignore: keep dist/ tracked Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# 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.
|