skills-vault/AGENTS.md

AGENTS.md

Project Overview

Skills Vault is a CLI for backing up and restoring Agent Skills.

The CLI entrypoint is src/cli.ts. It dispatches four commands:

• backup: snapshot installed skills into skvlt.yaml
• restore: install skills from a manifest
• doctor: inspect the local Skills Vault environment
• completion: print shell completion scripts

The codebase is intentionally small and organized around pure helpers plus command modules.

Repository Layout

• src/cli.ts: top-level CLI entrypoint and JSON/text output normalization
• src/commands/*.ts: user-facing commands
• src/internal/args: argument parsing
• src/internal/cli: themed output helpers
• src/internal/install: install planning, concurrency, and global state checks
• src/internal/manifest: manifest parsing/building types and helpers
• src/internal/paths: default paths and path formatting helpers
• src/internal/process: process wrappers for bunx and installed-skill inspection
• test/*.test.ts: Bun test coverage for command behavior, packaging, and edge cases
• .github/workflows: CI, release, and dependency review workflows

Tooling And Runtime

• Runtime/package manager: bun (packageManager: bun@1.3.11)
• Language: TypeScript run directly with Bun
• Formatter: Prettier
• Test runner: bun test
• Packaging target: npm package with src included in files

Use Bun for local development. Do not replace scripts with npm/yarn/pnpm equivalents unless the project is explicitly being migrated.

Setup Commands

Install dependencies:

bun install --frozen-lockfile

Show the CLI help locally:

bun run ./src/cli.ts --help

Run the packaged command through Bun:

bun run ./src/cli.ts doctor

Development Workflow

Useful repo scripts:

bun run backup
bun run backup:dry-run
bun run restore
bun run restore:dry-run
bun run test
bun run format
bun run format:check
bun run check

bun run check is the main pre-publish gate. It runs formatting checks, the full Bun test suite, and npm pack --dry-run --json.

If you touch GitHub workflow files, also run:

bunx prettier --check ".github/**/*.yml"

Testing Instructions

Run the full test suite:

bun test

Run a single test file:

bun test test/cli.test.ts

Target a specific test name when iterating:

bun test --test-name-pattern "prints top-level help"

Testing expectations:

• Add or update tests for any behavior change in CLI output, argument parsing, install planning, or manifest handling.
• Prefer focused unit tests around runCli(...), command entrypoints, and internal helpers with injected dependencies.
• Keep tests deterministic. Stub process and filesystem dependencies instead of relying on the caller machine state when possible.
• Packaging-related changes should still pass test/packaging.test.ts and npm pack --dry-run --json.

Command-Specific Notes

Backup

• Default manifest path is ./skvlt.yaml.
• Global scope reads from ~/.agents/.skill-lock.json.
• Project-scope backup currently requires --lock-file.

Examples:

bun run ./src/cli.ts backup
bun run ./src/cli.ts backup --dry-run
bun run ./src/cli.ts backup --project-scope --lock-file ./skills-lock.json

Restore

• Restore defaults to the scope recorded in the manifest.
• --project-scope forces project installation even if the manifest says global.
• Dry-run shows the derived bunx skills add ... commands.
• Live installs are intentionally serialized in lock-safe mode even when previewed concurrency is higher.

Examples:

bun run ./src/cli.ts restore --all
bun run ./src/cli.ts restore --only-source xixu-me/skills
bun run ./src/cli.ts restore --dry-run

Doctor

• doctor checks the Bun runtime, bunx skills --help, manifest presence, and global skill state consistency.
• It is the fastest sanity check when debugging local environment issues.

Completion

• Supported shells are bash, zsh, and powershell.

Code Style Guidelines

• Follow existing TypeScript + ESM patterns and keep imports grouped cleanly.
• Prefer small helpers with explicit types over large monolithic functions.
• Preserve the current command result shape: exitCode, stdout, stderr, optional errorCode, and optional structured payload.
• Match the existing output style helpers in src/internal/cli/theme instead of formatting raw strings ad hoc.
• Reuse path helpers in src/internal/paths for user-facing paths.
• Keep comments sparse and high-signal. The codebase uses short doc comments only where behavior needs context.
• Stick to ASCII unless a file already requires something else.

Build, Packaging, And Release

Pre-publish verification:

bun run check

Manual tarball check:

npm pack --dry-run --json

CI behavior:

• CI runs on main pushes and pull requests on Ubuntu and Windows.
• CI installs with bun install --frozen-lockfile.
• CI checks formatting, workflow formatting, tests, and a smoke install of the packed tarball.

Release behavior:

• Release runs on v*.*.* tags and workflow_dispatch.
• Release verifies the Git tag version matches package.json.
• npm publish uses trusted publishing via GitHub OIDC; do not add legacy token-based publish steps unless the release model changes.

Pull Request Guidance

Before submitting a change, run:

bun run check

Also run the workflow formatting check if you changed .github/workflows/*.yml.

When changing package metadata or release behavior, verify:

• the bin.skvlt entry still points to src/cli.ts
• publishable assets are still included as expected
• the tarball smoke path still works after npm pack

Troubleshooting

• If restore reports global state mismatch, inspect ~/.agents/.skill-lock.json and ~/.agents/skills.
• If local environment checks fail, start with bun run ./src/cli.ts doctor.
• If packaging tests fail, confirm all publish-required files referenced by tests are present in the repo snapshot.
• If command output assertions fail, check whether ANSI formatting or help text structure changed unintentionally.