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:
45
.wiki/concepts/active-platform-decision.md
Normal file
45
.wiki/concepts/active-platform-decision.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: "Decision: active-platform skill"
|
||||
type: concept
|
||||
updated: 2026-04-28
|
||||
---
|
||||
|
||||
# Decision: `active-platform` skill
|
||||
|
||||
_2026-04-28._
|
||||
|
||||
## Problem
|
||||
|
||||
The user develops on multiple machines (Windows primary, Linux/macOS secondary). I was generating bash one-liners by default — wrong shell for their daily workstation. Need a way to make Windows/PowerShell the default and switch on a phrase.
|
||||
|
||||
## Options weighed
|
||||
|
||||
- **Project memory** — wrong scope (project-only, doesn't cross repos).
|
||||
- **Global `~/.claude/CLAUDE.md`** — right scope, simple, but the user explicitly preferred a skill: "поживём со скиллом" (let's live with a skill and iterate).
|
||||
- **New skill** ← chosen.
|
||||
|
||||
The user's reasoning for the skill route: it's a discoverable, shareable artifact that lives next to their other 12 skills, and it can evolve with the same edit/build/install loop.
|
||||
|
||||
## What the skill does
|
||||
|
||||
Switches command/example generation between Windows / Linux / macOS based on session signals. Default = Windows + PowerShell. Trigger phrases in RU + EN (e.g. "мы на винде", "we're on Linux"). The rule applies only to **user-facing output** — tool calls still follow the harness's `Shell:` line.
|
||||
|
||||
Full spec: [`skills/active-platform/SKILL.md`](../../skills/active-platform/SKILL.md).
|
||||
|
||||
## Why this is a skill, not memory
|
||||
|
||||
- **Discoverability:** appears in `available_skills` list, can be re-read or audited.
|
||||
- **Cross-repo:** installed into `~/.claude/skills/`, applies in every session regardless of project.
|
||||
- **Iterable:** lives in this repo's `skills/` so we can edit + reinstall as we learn what triggers and exceptions actually happen in practice.
|
||||
|
||||
## Wired into `project-bootstrap`
|
||||
|
||||
The default platform should travel with every new project we create. Updated `project-bootstrap` so its `CLAUDE.md.template` adds a fifth trigger line: `we're on Windows`. That line is one of `active-platform`'s recognized switches, so any project bootstrapped from now on starts pinned to Windows / PowerShell. If the user is bootstrapping on a Linux/macOS host, the `SKILL.md` Step 5 note tells them to swap the line for `we're on Linux` / `we're on macOS`.
|
||||
|
||||
Backfilled the same line into this repo's own `CLAUDE.md` (which was created from the old template).
|
||||
|
||||
## Open questions to revisit
|
||||
|
||||
- Are the trigger phrases comprehensive enough? Add real-world examples as they come up.
|
||||
- WSL handling — currently treated as Linux. Reconsider if user has WSL-specific needs.
|
||||
- macOS divergences (BSD coreutils, Homebrew) — minimal coverage now, expand if user actually uses macOS often.
|
||||
42
.wiki/concepts/build-notes.md
Normal file
42
.wiki/concepts/build-notes.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Build Notes
|
||||
type: concept
|
||||
updated: 2026-04-28
|
||||
---
|
||||
|
||||
# Build Notes
|
||||
|
||||
Practical gotchas around building `.skill` archives.
|
||||
|
||||
## Why `build.ps1` exists alongside `build.sh`
|
||||
|
||||
The user is on Windows; the install target may be Linux/macOS. So archives must be portable.
|
||||
|
||||
**Windows PowerShell 5.1's `Compress-Archive` (v1.0.1.0) writes ZIP entries with backslashes** (e.g. `caveman\SKILL.md`). Linux/macOS `unzip` then either fails or extracts the literal name as a single file. Verified: archives produced by `Compress-Archive` listed entries like `caveman\SKILL.md`.
|
||||
|
||||
Workarounds considered:
|
||||
- Install `zip.exe` → adds a Windows dep we don't want.
|
||||
- PowerShell 7's `Compress-Archive` is fixed → can't assume PS7 is installed.
|
||||
- **Use .NET `System.IO.Compression.ZipArchive` directly** ← chosen. Walks files, adds entries with `path -replace '\\','/'`. Spec-compliant ZIPs everywhere.
|
||||
|
||||
`build.ps1` does that. `build.sh` prefers `zip` (one-liner, fast on *nix), and on Windows-without-`zip` it falls back to invoking `build.ps1` via `powershell.exe`.
|
||||
|
||||
## ZIP layout the loader expects
|
||||
|
||||
Looking at the canonical `~/.claude/skills/<name>/` layout, the `.skill` archive should contain a single top-level directory `<name>/` with `SKILL.md` plus optional `assets/`, `references/`, etc. inside.
|
||||
|
||||
`zip -qr dist/<name>.skill <name>` (run from `skills/`) does this naturally. The .NET path adds an explicit `<name>/` prefix to each entry.
|
||||
|
||||
## Extracting `.skill` files
|
||||
|
||||
A `.skill` file is just a renamed `.zip`. To extract on Windows:
|
||||
|
||||
```powershell
|
||||
Copy-Item project-bootstrap.skill project-bootstrap.zip
|
||||
Expand-Archive -Path project-bootstrap.zip -DestinationPath ~/.claude/skills/
|
||||
Remove-Item project-bootstrap.zip
|
||||
```
|
||||
|
||||
On *nix: `unzip dist/project-bootstrap.skill -d ~/.claude/skills/`.
|
||||
|
||||
(Our `install.sh` skips this entirely — it copies from `skills/` directly. Extraction-from-archive is only needed when you don't have the source tree, e.g. when sharing a single `.skill` file with someone else.)
|
||||
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.
|
||||
56
.wiki/concepts/wiki-realignment.md
Normal file
56
.wiki/concepts/wiki-realignment.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Wiki realignment to Karpathy canon
|
||||
type: concept
|
||||
updated: 2026-04-28
|
||||
---
|
||||
|
||||
# Wiki realignment to Karpathy canon
|
||||
|
||||
_2026-04-28._
|
||||
|
||||
## What was wrong
|
||||
|
||||
`project-bootstrap` Step 3 was creating `.wiki/SUMMARY.md`, `WORKFLOW.md`,
|
||||
and a `source/` folder. **None of these match** Karpathy's LLM Wiki pattern
|
||||
or what the `wiki-maintainer` skill reads:
|
||||
|
||||
| Bootstrap created | Canon expects |
|
||||
|---|---|
|
||||
| `SUMMARY.md` | `index.md` |
|
||||
| `WORKFLOW.md` (duplicates skill) | (no such file — workflow lives in `wiki-maintainer`) |
|
||||
| `source/` (singular) | `sources/` (plural) |
|
||||
| (missing) | `.wiki/CLAUDE.md` schema |
|
||||
| (missing) | `log.md` (append-only op log) |
|
||||
| (missing) | `entities/`, `concepts/`, `packages/`, `overview.md` |
|
||||
| (missing) | `raw/README.md` |
|
||||
|
||||
When `wiki-maintainer` triggered, it had to bend around an invented layout:
|
||||
the schema file it expects to read first wasn't there at all, and the
|
||||
catalog had the wrong name.
|
||||
|
||||
## Fix
|
||||
|
||||
Rewrote `project-bootstrap` Step 3 to create the canonical layout verbatim:
|
||||
|
||||
```
|
||||
.wiki/
|
||||
CLAUDE.md schema (project-specific conventions)
|
||||
index.md catalog of all pages
|
||||
log.md append-only op log: ## [YYYY-MM-DD] op | desc
|
||||
overview.md single human-readable project overview
|
||||
raw/README.md raw/ is immutable; this documents that
|
||||
entities/ concepts/ packages/ sources/ (with .gitkeep)
|
||||
```
|
||||
|
||||
Each file has its initial content baked into the SKILL.md so bootstrap can
|
||||
write them without external assets.
|
||||
|
||||
The Karpathy gist is pinned at the top of `.wiki/CLAUDE.md`:
|
||||
**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f**
|
||||
|
||||
## What about this repo's `.wiki/`?
|
||||
|
||||
This repo was itself bootstrapped with the old buggy layout. Its `.wiki/`
|
||||
still uses `SUMMARY.md` + `source/`. Migrating to canon is a directory
|
||||
rename + file moves; queued as a backlog task to do consciously rather than
|
||||
silently bundling it here.
|
||||
Reference in New Issue
Block a user