skillfold: Instructions file for Claude Code

Skillfold

Declarative skill manager for Claude config. Declare skills and rules in skillfold.yaml, pin exact revisions in skillfold.lock, install them into .claude/skills and .claude/rules.

GitHub

• Repo: https://github.com/byronxlg/skillfold
• Issues, PRs, releases, actions, and all other GitHub features are available for use

Operations

• runbook/ - how the package, site and blog cron ship, what healthy means, and how to roll back (fleet standard, tier 3)

Quick Reference

• Run the CLI: npx tsx src/cli.ts <command>
• Install skills: npx tsx src/cli.ts install (--frozen for CI-exact installs)
• Add a skill: npx tsx src/cli.ts add <source>
• Verify sync: npx tsx src/cli.ts check
• List status: npx tsx src/cli.ts list
• Tests: npm test (node:test via tsx, no extra deps)
• Type check: npm run typecheck (src + scripts)
• Build: npm run build
• Build the blog: npm run build:blog (regenerates site/blog/, output is gitignored, except the marker-fenced block in site/index.html which is committed)
• Write a blog post: follow skills/blog-post/SKILL.md. The blog is current-events-first (news in the agent config / skill distribution / supply chain space), with an evergreen queue in docs/blog-todo.md as the quiet-week fallback. It is not a product blog.

Project Structure

src/
  cli.ts      - CLI entry point: arg parsing, command dispatch, output formatting
  manifest.ts - skillfold.yaml parsing, validation, comment-preserving add/remove edits
  source.ts   - source string parsing (local paths, github:, npm:) and @ref extraction
  skill.ts    - SKILL.md frontmatter parsing, skill directory reading, sha256 integrity hashing
  lock.ts     - skillfold.lock read/write and manifest-vs-lock diffing
  resolve.ts  - central resolver: manifest + lock -> concrete files, pin reuse, frozen mode
  github.ts   - GitHub ref -> SHA resolution and skill fetching (contents API, injectable fetch)
  npm.ts      - npm skill resolution: node_modules first, then registry via npm pack into cache
  cache.ts    - shared content cache (~/.cache/skillfold), keyed by SHA / exact version
  compose.ts  - composed skill generation (body concatenation, topological ordering)
  targets.ts  - install-target layouts (claude, codex) mapping targets to locations
  agentsmd.ts - managed rules block in AGENTS.md for the codex target
  install.ts  - sync into skillsDir (managed-dir safety, pruning) and offline check
  init.ts     - skillfold init scaffolding
  list.ts     - status table (ok / modified / not installed / not locked)
  search.ts   - npm registry search for skillfold-skill packages
  index.ts    - public API exports
  testutil.ts - test helpers (tmp dirs, fixture skills, fetch stub); excluded from build
library/      - 11 general-purpose skills published with the package (agentskills map)
site/         - static docs site deployed to GitHub Pages
  index.html    - landing page (page-specific CSS inline)
  assets/       - vendored fonts, base.css (shared chrome), blog.css
  blog/posts/   - blog sources: markdown + YAML frontmatter (the only committed blog files)
scripts/
  build-blog.ts - renders site/blog/posts/*.md into site/blog/, feed.xml,
                  sitemap.xml, robots.txt, and the marker-fenced block in index.html
skills/blog-post/ - repo-specific skill driving the weekly blog automation
docs/blog-todo.md - blog editorial state: news beats, fallback queue, rollouts, shipped log
docs/         - markdown docs (getting started, manifest, CLI, publishing)
skillfold.yaml         - this repo's own manifest (dogfood; installs from library/)
skillfold.schema.json  - JSON Schema for manifest validation and IDE autocompletion
action.yml             - GitHub Action wrapper for skillfold check