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) <noreply@anthropic.com>
This commit is contained in:
67
README.md
67
README.md
@@ -1,64 +1,81 @@
|
|||||||
# claude-skills
|
# claude-skills
|
||||||
|
|
||||||
Совместное хранилище и мастерская навыков для Claude.
|
> Russian version: [README.ru.md](README.ru.md).
|
||||||
|
|
||||||
|
Joint workshop and storage for Claude skills.
|
||||||
|
|
||||||
## About
|
## About
|
||||||
|
|
||||||
Здесь мы с Claude вместе разрабатываем, отлаживаем и храним скиллы:
|
A shared workspace where Claude and I author, debug, and ship skills together:
|
||||||
|
|
||||||
- **`skills/`** — редактируемые исходники (markdown + ассеты), source of truth
|
- **`skills/`** — editable sources (markdown + assets), the source of truth
|
||||||
- **`dist/`** — собранные `.skill` архивы, закоммичены в репо
|
- **`dist/`** — built `.skill` archives, committed to the repo
|
||||||
- **`scripts/`** — утилиты: `build.sh` (исходник → `.skill`), `install.sh` (исходник → `~/.claude/skills/`)
|
- **`scripts/`** — utilities: `build.sh` (source → `.skill`), `install.sh` (source → `~/.claude/skills/`)
|
||||||
- **`.wiki/`**, **`.tasks/`** — рабочие материалы и доска задач
|
- **`.wiki/`**, **`.tasks/`** — working notes and the task board
|
||||||
|
|
||||||
## Quick start
|
## Quick start
|
||||||
|
|
||||||
### Установить скиллы на новом компе
|
### Install skills on a fresh machine
|
||||||
|
|
||||||
|
**Windows (PowerShell):**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
git clone <repo> 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
|
```bash
|
||||||
git clone <repo> claude-skills
|
git clone <repo> claude-skills
|
||||||
cd 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
|
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
|
```bash
|
||||||
# 1. Правишь skills/<name>/SKILL.md (или ассеты)
|
# 1. Edit skills/<name>/SKILL.md (or its assets).
|
||||||
# 2. Раскатываешь правки в живые скиллы:
|
# 2. Push the changes into the live skill folder:
|
||||||
bash scripts/install.sh <name>
|
bash scripts/install.sh <name>
|
||||||
# 3. Пересобираешь архив (опц., но удобно делать перед коммитом):
|
# 3. Rebuild the archive (optional, but handy before a commit):
|
||||||
bash scripts/build.sh <name>
|
bash scripts/build.sh <name>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Собрать `.skill` архивы
|
### Build `.skill` archives
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bash scripts/build.sh # все
|
bash scripts/build.sh # all skills
|
||||||
bash scripts/build.sh caveman # один
|
bash scripts/build.sh caveman # one skill
|
||||||
```
|
```
|
||||||
|
|
||||||
`build.sh` использует `zip` если он есть (Linux/macOS) или делегирует в
|
`build.sh` uses `zip` when it's available (Linux/macOS) or delegates to
|
||||||
`scripts/build.ps1` через PowerShell (Windows без `zip`). На Windows
|
`scripts/build.ps1` via PowerShell (Windows without `zip`). On Windows you
|
||||||
можно сразу запускать `powershell scripts/build.ps1`.
|
can also run `powershell scripts/build.ps1` directly.
|
||||||
|
|
||||||
## Layout
|
## Layout
|
||||||
|
|
||||||
```
|
```
|
||||||
claude-skills/
|
claude-skills/
|
||||||
├── skills/ ← исходники (по папке на скилл)
|
├── skills/ ← sources (one folder per skill)
|
||||||
├── dist/ ← .skill архивы (коммитятся)
|
├── dist/ ← .skill archives (committed)
|
||||||
├── scripts/
|
├── scripts/
|
||||||
│ ├── build.sh / build.ps1
|
│ ├── build.sh / build.ps1
|
||||||
│ └── install.sh
|
│ └── install.sh
|
||||||
├── .wiki/ ← дизайн-доки, заметки
|
├── .wiki/ ← design docs, notes
|
||||||
├── .tasks/ ← STATUS.md
|
├── .tasks/ ← STATUS.md
|
||||||
├── CLAUDE.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).
|
||||||
|
|||||||
66
README.ru.md
Normal file
66
README.ru.md
Normal file
@@ -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 <repo> 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/<name>/SKILL.md (или ассеты)
|
||||||
|
# 2. Раскатываешь правки в живые скиллы:
|
||||||
|
bash scripts/install.sh <name>
|
||||||
|
# 3. Пересобираешь архив (опц., но удобно делать перед коммитом):
|
||||||
|
bash scripts/build.sh <name>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Собрать `.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).
|
||||||
104
skills/project-bootstrap/README.md
Normal file
104
skills/project-bootstrap/README.md
Normal file
@@ -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 `<task-slug>.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:
|
||||||
|
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|
||||||
Reference in New Issue
Block a user