vitya
9f54068de0
- skills/: editable sources for all 12 personal skills (caveman family, find-skills, project-bootstrap, task-status-wiki, using-context7, using-markitdown, wiki-maintainer, compress) - dist/: built .skill archives, committed (cross-machine deploy without needing zip on the target) - scripts/build.sh + build.ps1: zip skills/<name>/ into dist/<name>.skill; Windows fallback uses .NET ZipArchive (PS 5.1 Compress-Archive writes backslashes that break extraction on *nix) - scripts/install.sh: copy skills/<name>/ into ~/.claude/skills/<name>/ ($CLAUDE_SKILLS_DIR overrides target) - .wiki/source/repo-layout.md, build-notes.md: design + gotchas - .gitignore: keep dist/ tracked Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
37 lines
1.9 KiB
Markdown
37 lines
1.9 KiB
Markdown
# 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.)
|