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>
This commit is contained in:
59
.wiki/concepts/repo-layout.md
Normal file
59
.wiki/concepts/repo-layout.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user