Contributing to Skills Vault

Thanks for taking the time to contribute.

Skills Vault is intentionally small. The best contributions usually keep that spirit: focused changes, clear reasoning, and tests or docs updates where behavior changes.

Before You Start

Please read these first:

README.md for project scope and command overview
CODE_OF_CONDUCT.md for community expectations
SECURITY.md before reporting vulnerabilities

If you plan to make a substantial change, open an issue first so we can confirm the direction before code is written.

Good First Contributions

Helpful contributions include:

bug fixes with regression tests
documentation improvements
clearer CLI help text
tighter error handling around manifest parsing and install planning
focused UX improvements to backup, restore, doctor, and completion flows

Local Setup

This project uses Bun only.

bun install --frozen-lockfile

Useful local commands:

bun run ./src/cli.ts --help
bun run ./src/cli.ts doctor
bun run test
bun run format
bun run format:check
bun run check

Development Guidelines

Use Bun for development and testing.
Follow the existing TypeScript + ESM style.
Prefer small helpers with explicit types over large, multi-purpose functions.
Preserve the current command result shape: exitCode, stdout, stderr, optional errorCode, and optional payload.
Reuse existing output helpers in src/internal/cli and path helpers in src/internal/paths.
Keep comments sparse and high-signal.

Tests and Verification

Run the full verification gate before opening a pull request:

bun run check

If you changed GitHub workflow files, also run:

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

When behavior changes, add or update tests for:

CLI output and help text
argument parsing
install planning and concurrency behavior
manifest parsing and building
packaging expectations when publish behavior changes

Keep tests deterministic. Prefer injected dependencies and stubs over relying on caller machine state.

Pull Requests

Please keep pull requests focused and include:

a short explanation of the problem being solved
the approach you took
any user-facing CLI or docs changes
the verification commands you ran

If a change affects command output, include an example of the new output in the PR description when practical.

Reporting Bugs

Use the bug report issue template and include:

the command you ran
what you expected to happen
what actually happened
your OS and Bun version
relevant output from bunx skvlt doctor

Security Reports

Do not report security vulnerabilities in public issues or pull requests. Follow SECURITY.md instead.

Maintainer Expectations

This project is maintained on a best-effort basis. Reviews may take time, and not every feature request will fit the project scope. Clear, scoped proposals have the best chance of landing quickly.

3.0 KiB Raw Blame History