Files

vitya 4382fd36b9 refactor(wiki): migrate this repo's .wiki/ to canonical Karpathy layout

Stop being inconsistent with our own fixed project-bootstrap template.

- SUMMARY.md → index.md (catalog by type, with one-line hooks)
- source/*.md → concepts/*.md (with `git mv` so history is preserved)
- WORKFLOW.md removed (workflow lives in wiki-maintainer, not duplicated here)
- New: .wiki/CLAUDE.md (project schema, Karpathy gist URL pinned at top)
- New: log.md (append-only op log; backfilled with prior decisions)
- New: overview.md (single project intro page)
- New: raw/README.md (immutability note; replaces .gitkeep placeholder)
- Empty .gitkeep added to entities/, packages/, sources/
- Migrated pages got `type: concept` frontmatter

After this, wiki-maintainer reads .wiki/CLAUDE.md → index.md as it expects,
and the layout matches what newly-bootstrapped projects will look like.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-28 11:22:43 +03:00

2.5 KiB

Raw Permalink Blame History

title, type, updated

title	type	updated
Repo Layout & Skill Workflow	concept	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.

2.5 KiB Raw Permalink Blame History