From 724897d7c65a5214bc678efea5685ac7346f29e8 Mon Sep 17 00:00:00 2001 From: vitya Date: Tue, 28 Apr 2026 20:27:51 +0300 Subject: [PATCH] docs: add English README for project-bootstrap; translate root README - skills/project-bootstrap/README.md: new English README (modes, triggers, prerequisites, layout, install, see-also). - README.md: translated to English; both root READMEs cross-link. - README.ru.md: original Russian preserved (renamed from README.md); fixed broken `.wiki/source/repo-layout.md` link to point at the real path under `.wiki/concepts/`. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 67 ++++++++++++------- README.ru.md | 66 ++++++++++++++++++ skills/project-bootstrap/README.md | 104 +++++++++++++++++++++++++++++ 3 files changed, 212 insertions(+), 25 deletions(-) create mode 100644 README.ru.md create mode 100644 skills/project-bootstrap/README.md diff --git a/README.md b/README.md index 53b80d7..f151ed0 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,81 @@ # claude-skills -Совместное хранилище и мастерская навыков для Claude. +> Russian version: [README.ru.md](README.ru.md). + +Joint workshop and storage for Claude skills. ## About -Здесь мы с Claude вместе разрабатываем, отлаживаем и храним скиллы: +A shared workspace where Claude and I author, debug, and ship skills together: -- **`skills/`** — редактируемые исходники (markdown + ассеты), source of truth -- **`dist/`** — собранные `.skill` архивы, закоммичены в репо -- **`scripts/`** — утилиты: `build.sh` (исходник → `.skill`), `install.sh` (исходник → `~/.claude/skills/`) -- **`.wiki/`**, **`.tasks/`** — рабочие материалы и доска задач +- **`skills/`** — editable sources (markdown + assets), the source of truth +- **`dist/`** — built `.skill` archives, committed to the repo +- **`scripts/`** — utilities: `build.sh` (source → `.skill`), `install.sh` (source → `~/.claude/skills/`) +- **`.wiki/`**, **`.tasks/`** — working notes and the task board ## Quick start -### Установить скиллы на новом компе +### Install skills on a fresh machine + +**Windows (PowerShell):** + +```powershell +git clone claude-skills +cd claude-skills +bash scripts/install.sh # copies every skills/* into ~/.claude/skills/ +# or only specific ones: +bash scripts/install.sh caveman wiki-maintainer +``` + +**Linux / macOS (bash):** ```bash git clone claude-skills cd claude-skills -bash scripts/install.sh # копирует все skills/* в ~/.claude/skills/ -# или конкретные: +bash scripts/install.sh # copies every skills/* into ~/.claude/skills/ +# or only specific ones: bash scripts/install.sh caveman wiki-maintainer ``` -Цель установки можно переопределить переменной `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`. +The install target can be overridden with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`. -### Отредактировать скилл +> `install.sh` works on Windows under git-bash. A native `install.ps1` is on the task board but not yet implemented. + +### Edit a skill ```bash -# 1. Правишь skills//SKILL.md (или ассеты) -# 2. Раскатываешь правки в живые скиллы: +# 1. Edit skills//SKILL.md (or its assets). +# 2. Push the changes into the live skill folder: bash scripts/install.sh -# 3. Пересобираешь архив (опц., но удобно делать перед коммитом): +# 3. Rebuild the archive (optional, but handy before a commit): bash scripts/build.sh ``` -### Собрать `.skill` архивы +### Build `.skill` archives ```bash -bash scripts/build.sh # все -bash scripts/build.sh caveman # один +bash scripts/build.sh # all skills +bash scripts/build.sh caveman # one skill ``` -`build.sh` использует `zip` если он есть (Linux/macOS) или делегирует в -`scripts/build.ps1` через PowerShell (Windows без `zip`). На Windows -можно сразу запускать `powershell scripts/build.ps1`. +`build.sh` uses `zip` when it's available (Linux/macOS) or delegates to +`scripts/build.ps1` via PowerShell (Windows without `zip`). On Windows you +can also run `powershell scripts/build.ps1` directly. ## Layout ``` claude-skills/ -├── skills/ ← исходники (по папке на скилл) -├── dist/ ← .skill архивы (коммитятся) +├── skills/ ← sources (one folder per skill) +├── dist/ ← .skill archives (committed) ├── scripts/ │ ├── build.sh / build.ps1 │ └── install.sh -├── .wiki/ ← дизайн-доки, заметки +├── .wiki/ ← design docs, notes ├── .tasks/ ← STATUS.md ├── CLAUDE.md -└── README.md +└── README.md (this file — see README.ru.md for Russian) ``` -Подробнее про принципы и решения — в [`.wiki/source/repo-layout.md`](.wiki/source/repo-layout.md). +For the principles and decisions behind this layout see +[`.wiki/concepts/repo-layout.md`](.wiki/concepts/repo-layout.md). diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..ee5d28a --- /dev/null +++ b/README.ru.md @@ -0,0 +1,66 @@ +# claude-skills + +> English version: [README.md](README.md). + +Совместное хранилище и мастерская навыков для Claude. + +## About + +Здесь мы с Claude вместе разрабатываем, отлаживаем и храним скиллы: + +- **`skills/`** — редактируемые исходники (markdown + ассеты), source of truth +- **`dist/`** — собранные `.skill` архивы, закоммичены в репо +- **`scripts/`** — утилиты: `build.sh` (исходник → `.skill`), `install.sh` (исходник → `~/.claude/skills/`) +- **`.wiki/`**, **`.tasks/`** — рабочие материалы и доска задач + +## Quick start + +### Установить скиллы на новом компе + +```bash +git clone claude-skills +cd claude-skills +bash scripts/install.sh # копирует все skills/* в ~/.claude/skills/ +# или конкретные: +bash scripts/install.sh caveman wiki-maintainer +``` + +Цель установки можно переопределить переменной `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh`. + +### Отредактировать скилл + +```bash +# 1. Правишь skills//SKILL.md (или ассеты) +# 2. Раскатываешь правки в живые скиллы: +bash scripts/install.sh +# 3. Пересобираешь архив (опц., но удобно делать перед коммитом): +bash scripts/build.sh +``` + +### Собрать `.skill` архивы + +```bash +bash scripts/build.sh # все +bash scripts/build.sh caveman # один +``` + +`build.sh` использует `zip` если он есть (Linux/macOS) или делегирует в +`scripts/build.ps1` через PowerShell (Windows без `zip`). На Windows +можно сразу запускать `powershell scripts/build.ps1`. + +## Layout + +``` +claude-skills/ +├── skills/ ← исходники (по папке на скилл) +├── dist/ ← .skill архивы (коммитятся) +├── scripts/ +│ ├── build.sh / build.ps1 +│ └── install.sh +├── .wiki/ ← дизайн-доки, заметки +├── .tasks/ ← STATUS.md +├── CLAUDE.md +└── README.md +``` + +Подробнее про принципы и решения — в [`.wiki/concepts/repo-layout.md`](.wiki/concepts/repo-layout.md). diff --git a/skills/project-bootstrap/README.md b/skills/project-bootstrap/README.md new file mode 100644 index 0000000..0740ea6 --- /dev/null +++ b/skills/project-bootstrap/README.md @@ -0,0 +1,104 @@ +# project-bootstrap + +Initializes or upgrades a project workspace in one pass: git, `.gitignore`, +`README.md`, `.wiki/` (Karpathy's LLM Wiki layout), `.tasks/` (per-task board), +and `CLAUDE.md` with skill triggers. + +Operates in two modes, picked automatically: + +- **init** — empty or near-empty folder. Creates everything from scratch. +- **upgrade** — existing project. Detects what's already there, only fills the + gaps. Never overwrites without explicit confirmation. + +## When it triggers + +The skill auto-activates on phrases like: + +- "initialize project", "bootstrap", "setup project" +- "upgrade project", "add wiki", "add tasks" +- "start project", "set everything up" +- "let's start a project", "init" + +It also triggers when an agent is launched in a fresh folder that the user +clearly intends to turn into a workspace. + +## Prerequisites + +`project-bootstrap` does not lay out `.wiki/` or `.tasks/` by itself — it +delegates to two companion skills, which must be installed on the machine +running it: + +- [`setup-wiki`](../setup-wiki/) — creates the canonical `.wiki/` layout. +- [`setup-tasks`](../setup-tasks/) — creates the canonical `.tasks/` layout. + +If either is missing, `project-bootstrap` stops with a clear error rather +than falling back to ad-hoc creation. This keeps layout drift between +projects bootstrapped at different times debuggable. + +## What it creates + +| Path | Source | Notes | +|---|---|---| +| `.git/` | `git init` | Skipped if repo already initialized. | +| `.gitignore` | `assets/.gitignore.template` | Skipped if file exists. | +| `README.md` | minimal stub | Skipped if file exists. | +| `.wiki/` | delegated to `setup-wiki` | Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`. | +| `.tasks/` | delegated to `setup-tasks` | Canonical board — `STATUS.md` plus per-task `.md` files. | +| `CLAUDE.md` | `assets/CLAUDE.md.template` | Skill triggers (`use superpowers`, `use project wiki`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. | +| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. | + +## Workflow + +1. **Detect mode.** Inspect the current directory — git, `.wiki/`, `.tasks/`, + `CLAUDE.md`, `README.md` — and print a single summary block: what was + found, what will be created, what will be skipped. +2. **Confirm.** One question, one confirmation. Nothing is written before the + user agrees. +3. **Steps 1–5.** Create or skip each piece in order — git, README, `.wiki/`, + `.tasks/`, `CLAUDE.md`. Steps 3 and 4 delegate to the setup-skills. +4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of + `project-bootstrap`, `setup-wiki`, and `setup-tasks` used. +5. **Commit.** `chore: bootstrap project structure` for fresh repos, or + `chore: upgrade project structure` adding only the new files for existing + ones. Pushes only on explicit user request. +6. **Summary.** Final report — what was created, what was skipped, suggested + next step. + +## Rules + +- Never overwrite an existing file without explicit user confirmation. +- Always show the plan before touching the filesystem. +- Never invent project details — read what's already there. +- Commit only files just created — never touch the rest of the tree. +- Push only after the user explicitly says so. + +## Install + +From the repo root: + +**Windows (PowerShell):** + +```powershell +bash scripts/install.sh project-bootstrap +``` + +**Linux / macOS (bash):** + +```bash +bash scripts/install.sh project-bootstrap +``` + +`install.sh` works on Windows under git-bash. A native `install.ps1` is +[planned](../../.tasks/STATUS.md) but not required. + +The skill installs to `~/.claude/skills/project-bootstrap/`. Override the +target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`. + +## See also + +- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` layout. +- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` layout. +- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`. +- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`. +- Karpathy's LLM Wiki gist: +