vitya
4382fd36b9
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>
43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
---
|
|
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.)
|