docs: refresh project docs and community templates
This commit is contained in:
xixu-me committed
1 parent
8ef4ad70d7
commit
9f8257087b
15 files changed
+682
-555
No files matched your search
@@ -1,5 +1,5 @@
|
||||
name: Bug report
|
||||
description: Report a reproducible bug or regression
|
||||
description: Report a reproducible problem in Skills Vault
|
||||
title: "[Bug]: "
|
||||
labels:
|
||||
- bug
|
||||
@@ -7,48 +7,56 @@ body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for reporting a bug. Please include enough detail for someone else to reproduce it.
|
||||
- type: input
|
||||
Thanks for reporting a bug.
|
||||
|
||||
Please do not use this template for security issues. Follow the private reporting process in `SECURITY.md` instead.
|
||||
- type: textarea
|
||||
id: summary
|
||||
attributes:
|
||||
label: Summary
|
||||
description: What went wrong?
|
||||
placeholder: A short description of the problem
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: steps
|
||||
attributes:
|
||||
label: Reproduction steps
|
||||
description: Share the exact steps, commands, and inputs used
|
||||
placeholder: |
|
||||
1. Run ...
|
||||
2. Open ...
|
||||
3. Observe ...
|
||||
label: What happened?
|
||||
description: Describe the problem and the command you ran.
|
||||
placeholder: "`bunx skvlt restore --all` exited with ..."
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: expected
|
||||
attributes:
|
||||
label: Expected behavior
|
||||
label: What did you expect to happen?
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: actual
|
||||
id: repro
|
||||
attributes:
|
||||
label: Actual behavior
|
||||
label: How can we reproduce it?
|
||||
description: Share the smallest set of steps that reproduces the issue.
|
||||
placeholder: |
|
||||
1. Run ...
|
||||
2. Use this manifest ...
|
||||
3. Observe ...
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: environment
|
||||
id: doctor
|
||||
attributes:
|
||||
label: Environment
|
||||
description: OS, shell, Bun version, package version, and anything else relevant
|
||||
validations:
|
||||
required: true
|
||||
label: Relevant `bunx skvlt doctor` output
|
||||
render: shell
|
||||
description: Paste the relevant parts of the `doctor` output if available.
|
||||
- type: textarea
|
||||
id: logs
|
||||
attributes:
|
||||
label: Logs or screenshots
|
||||
description: Paste relevant output here
|
||||
label: Relevant CLI output or stack trace
|
||||
render: shell
|
||||
- type: input
|
||||
id: bun
|
||||
attributes:
|
||||
label: Bun version
|
||||
placeholder: "1.3.11"
|
||||
validations:
|
||||
required: true
|
||||
- type: input
|
||||
id: os
|
||||
attributes:
|
||||
label: Operating system
|
||||
placeholder: "Windows 11, macOS 15, Ubuntu 24.04"
|
||||
validations:
|
||||
required: true
|
||||
@@ -1,8 +1,5 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Security report
|
||||
url: https://github.com/xixu-me/skills-vault/blob/main/SECURITY.md
|
||||
about: Please follow the private security reporting process in SECURITY.md.
|
||||
- name: Contribution guide
|
||||
url: https://github.com/xixu-me/skills-vault/blob/main/CONTRIBUTING.md
|
||||
about: Read the contribution workflow and local development expectations.
|
||||
- name: Support and troubleshooting
|
||||
url: https://github.com/xixu-me/skills-vault/blob/main/SUPPORT.md
|
||||
about: Read the support guide before opening an issue.
|
||||
@@ -1,30 +1,35 @@
|
||||
name: Feature request
|
||||
description: Propose a focused improvement to the CLI or developer workflow
|
||||
description: Propose an improvement to Skills Vault
|
||||
title: "[Feature]: "
|
||||
labels:
|
||||
- enhancement
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for suggesting an improvement.
|
||||
|
||||
Focused proposals are easier to evaluate and much more likely to land quickly.
|
||||
- type: textarea
|
||||
id: problem
|
||||
attributes:
|
||||
label: Problem to solve
|
||||
description: What user problem or workflow gap are you seeing?
|
||||
label: What problem are you trying to solve?
|
||||
description: Describe the user or maintainer pain point first.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: proposal
|
||||
attributes:
|
||||
label: Proposed change
|
||||
description: Describe the behavior you want
|
||||
label: What change would you like to see?
|
||||
description: Describe the behavior, CLI UX, or docs change you want.
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: alternatives
|
||||
attributes:
|
||||
label: Alternatives considered
|
||||
description: What workarounds or alternative designs did you consider?
|
||||
label: What alternatives have you considered?
|
||||
- type: textarea
|
||||
id: context
|
||||
id: scope
|
||||
attributes:
|
||||
label: Additional context
|
||||
description: Examples, prior art, links, or constraints
|
||||
label: Scope and trade-offs
|
||||
description: Mention any compatibility concerns, manifest changes, or CLI output changes.
|
||||
@@ -1,32 +0,0 @@
|
||||
name: Question
|
||||
description: Ask a usage or behavior question with enough context to triage it
|
||||
title: "[Question]: "
|
||||
labels:
|
||||
- question
|
||||
body:
|
||||
- type: textarea
|
||||
id: question
|
||||
attributes:
|
||||
label: What do you need help with?
|
||||
description: Describe the question as clearly as you can
|
||||
validations:
|
||||
required: true
|
||||
- type: textarea
|
||||
id: context
|
||||
attributes:
|
||||
label: Context
|
||||
description: Commands, manifests, environment details, or logs that may help
|
||||
- type: dropdown
|
||||
id: category
|
||||
attributes:
|
||||
label: Category
|
||||
options:
|
||||
- Installation
|
||||
- Backup
|
||||
- Restore
|
||||
- Doctor
|
||||
- Completion
|
||||
- Packaging or publishing
|
||||
- Other
|
||||
validations:
|
||||
required: true
|
||||
@@ -1,21 +1,14 @@
|
||||
## Summary
|
||||
|
||||
- What changed?
|
||||
- Why is this change needed?
|
||||
Describe the problem and the change in a few sentences.
|
||||
|
||||
## Verification
|
||||
## Testing
|
||||
|
||||
- [ ] `bun run test`
|
||||
- [ ] `bun run check`
|
||||
- [ ] `bunx prettier --check ".github/**/*.yml"` if workflow files changed
|
||||
|
||||
Describe any manual verification you performed:
|
||||
## Checklist
|
||||
|
||||
## Documentation
|
||||
|
||||
- [ ] No documentation changes needed
|
||||
- [ ] README updated
|
||||
- [ ] CONTRIBUTING or support docs updated
|
||||
|
||||
## Notes
|
||||
|
||||
Add follow-up work, known limitations, or anything reviewers should pay attention to.
|
||||
- [ ] I linked the relevant issue, or explained why one was not needed.
|
||||
- [ ] I updated tests or docs where behavior changed.
|
||||
- [ ] I did not use this PR for a security disclosure.
|
||||
@@ -0,0 +1,206 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Project Overview
|
||||
|
||||
Skills Vault is a CLI for backing up and restoring [Agent Skills](https://agentskills.io).
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
bun install --frozen-lockfile
|
||||
```
|
||||
|
||||
Show the CLI help locally:
|
||||
|
||||
```sh
|
||||
bun run ./src/cli.ts --help
|
||||
```
|
||||
|
||||
Run the packaged command through Bun:
|
||||
|
||||
```sh
|
||||
bun run ./src/cli.ts doctor
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
Useful repo scripts:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
bunx prettier --check ".github/**/*.yml"
|
||||
```
|
||||
|
||||
## Testing Instructions
|
||||
|
||||
Run the full test suite:
|
||||
|
||||
```sh
|
||||
bun test
|
||||
```
|
||||
|
||||
Run a single test file:
|
||||
|
||||
```sh
|
||||
bun test test/cli.test.ts
|
||||
```
|
||||
|
||||
Target a specific test name when iterating:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
bun run check
|
||||
```
|
||||
|
||||
Manual tarball check:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
+59
-34
@@ -1,50 +1,75 @@
|
||||
# Code of Conduct
|
||||
# Contributor Covenant Code of Conduct
|
||||
|
||||
## Our Commitment
|
||||
## Our Pledge
|
||||
|
||||
Skills Vault aims to be a welcoming, respectful, and constructive project for everyone who participates in issues, pull requests, code review, and other community interactions.
|
||||
We as members, contributors, and maintainers pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
## Expected Behavior
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
|
||||
|
||||
Examples of behavior that help build a healthy community include:
|
||||
## Our Standards
|
||||
|
||||
- Being respectful and considerate in communication
|
||||
- Assuming good intent while giving direct, technical feedback
|
||||
- Focusing discussion on the work, not the person
|
||||
- Sharing context, reproduction steps, and evidence when reporting problems
|
||||
- Accepting that disagreement can be handled professionally
|
||||
Examples of behavior that contributes to a positive environment for our community include:
|
||||
|
||||
## Unacceptable Behavior
|
||||
- demonstrating empathy and kindness toward other people
|
||||
- being respectful of differing opinions, viewpoints, and experiences
|
||||
- giving and gracefully accepting constructive feedback
|
||||
- accepting responsibility and apologizing to those affected by our mistakes
|
||||
- focusing on what is best not just for us as individuals, but for the overall community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
- Harassment, threats, or personal attacks
|
||||
- Discriminatory or demeaning language
|
||||
- Repeatedly derailing technical discussions
|
||||
- Publishing private information without consent
|
||||
- Bad-faith behavior intended to exhaust or intimidate others
|
||||
- the use of sexualized language or imagery, and sexual attention or advances of any kind
|
||||
- trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- public or private harassment
|
||||
- publishing others' private information, such as a physical or email address, without their explicit permission
|
||||
- other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement Responsibilities
|
||||
|
||||
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies to project spaces, including:
|
||||
|
||||
- GitHub issues
|
||||
- Pull requests
|
||||
- Code review discussions
|
||||
- Project documentation and examples
|
||||
|
||||
## Reporting
|
||||
|
||||
If you experience or witness behavior that violates this Code of Conduct, report it privately to the maintainer at [email protected].
|
||||
|
||||
Please include:
|
||||
|
||||
- A description of what happened
|
||||
- Links, screenshots, or other relevant context
|
||||
- Any immediate safety concerns
|
||||
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official project email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
|
||||
|
||||
## Enforcement
|
||||
|
||||
The maintainer will review reports in good faith and may take any action needed to protect the community and project, including warning, moderating, or removing content, temporarily restricting participation, or permanently banning contributors from project spaces.
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported privately through the maintainer contact methods listed at [xi-xu.me/contact](https://xi-xu.me/#contact). Reports will be reviewed and investigated promptly and fairly.
|
||||
|
||||
Retaliation against anyone who reports a concern in good faith is not acceptable.
|
||||
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
|
||||
|
||||
## Enforcement Guidelines
|
||||
|
||||
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
|
||||
|
||||
### 1. Correction
|
||||
|
||||
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
|
||||
|
||||
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community Impact**: A violation through a single incident or series of actions.
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
|
||||
|
||||
### 3. Temporary Ban
|
||||
|
||||
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
|
||||
|
||||
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at [contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
|
||||
|
||||
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
|
||||
+71
-58
@@ -1,93 +1,106 @@
|
||||
# Contributing to Skills Vault
|
||||
|
||||
Thanks for your interest in contributing to Skills Vault.
|
||||
Thanks for taking the time to contribute.
|
||||
|
||||
This project is a CLI for backing up and restoring Agent Skills. We welcome bug reports, documentation improvements, tests, and focused feature proposals.
|
||||
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
|
||||
|
||||
- Read the [README](./README.md) for the project overview and command surface.
|
||||
- Read the [Code of Conduct](./CODE_OF_CONDUCT.md) before participating.
|
||||
- For security issues, follow [SECURITY.md](./SECURITY.md) instead of opening a public issue.
|
||||
Please read these first:
|
||||
|
||||
## Ways to Contribute
|
||||
- [README.md](./README.md) for project scope and command overview
|
||||
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for community expectations
|
||||
- [SECURITY.md](./SECURITY.md) before reporting vulnerabilities
|
||||
|
||||
- Report bugs
|
||||
- Improve documentation
|
||||
- Add or improve tests
|
||||
- Propose targeted CLI improvements
|
||||
- Fix small usability issues or polish error messages
|
||||
If you plan to make a substantial change, open an issue first so we can confirm the direction before code is written.
|
||||
|
||||
If you plan to work on a larger change, open an issue first so we can agree on scope before implementation starts.
|
||||
## Good First Contributions
|
||||
|
||||
## Development Setup
|
||||
Helpful contributions include:
|
||||
|
||||
Prerequisites:
|
||||
- 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
|
||||
|
||||
- Bun `>=1.3.11`
|
||||
## Local Setup
|
||||
|
||||
Install dependencies:
|
||||
This project uses Bun only.
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```sh
|
||||
bun install --frozen-lockfile
|
||||
```
|
||||
|
||||
Useful commands:
|
||||
Useful local commands:
|
||||
|
||||
```bash
|
||||
bun run format
|
||||
```sh
|
||||
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
|
||||
```
|
||||
|
||||
## Contribution Workflow
|
||||
## Development Guidelines
|
||||
|
||||
1. Fork the repository and create a focused branch.
|
||||
2. Make the smallest change that solves the problem well.
|
||||
3. Add or update tests when behavior changes.
|
||||
4. Run `bun run check` before opening a pull request.
|
||||
5. Update documentation when user-facing behavior changes.
|
||||
6. Open a pull request with a clear description of the change and why it is needed.
|
||||
- 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.
|
||||
|
||||
## Pull Request Guidelines
|
||||
## Tests and Verification
|
||||
|
||||
Good pull requests are:
|
||||
Run the full verification gate before opening a pull request:
|
||||
|
||||
- Small and focused
|
||||
- Clear about user impact
|
||||
- Covered by tests when behavior changes
|
||||
- Updated to match the current CLI behavior and docs
|
||||
```sh
|
||||
bun run check
|
||||
```
|
||||
|
||||
Please include:
|
||||
If you changed GitHub workflow files, also run:
|
||||
|
||||
- What changed
|
||||
- Why it changed
|
||||
- How you verified it
|
||||
- Any follow-up work or known limitations
|
||||
```sh
|
||||
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
|
||||
|
||||
Open a GitHub issue with:
|
||||
Use the bug report issue template and include:
|
||||
|
||||
- Your environment
|
||||
- The command you ran
|
||||
- Expected behavior
|
||||
- Actual behavior
|
||||
- Logs or screenshots when relevant
|
||||
- A small reproduction, if possible
|
||||
- the command you ran
|
||||
- what you expected to happen
|
||||
- what actually happened
|
||||
- your OS and Bun version
|
||||
- relevant output from `bunx skvlt doctor`
|
||||
|
||||
## Feature Requests
|
||||
## Security Reports
|
||||
|
||||
Feature requests are welcome, especially when they are:
|
||||
Do not report security vulnerabilities in public issues or pull requests. Follow [SECURITY.md](./SECURITY.md) instead.
|
||||
|
||||
- Clearly scoped
|
||||
- Tied to a concrete user problem
|
||||
- Consistent with the project's CLI-first design
|
||||
## Maintainer Expectations
|
||||
|
||||
## Style Notes
|
||||
|
||||
- Keep changes consistent with the existing TypeScript and CLI patterns.
|
||||
- Prefer precise error messages and deterministic output.
|
||||
- Avoid unrelated refactors in the same pull request.
|
||||
|
||||
Thanks for helping make Skills Vault easier to use and maintain.
|
||||
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.
|
||||
@@ -2,133 +2,55 @@
|
||||
|
||||
**_[汉语](./README.zh.md)_**
|
||||
|
||||
The CLI for backing up and restoring [Agent Skills](https://agentskills.io).
|
||||
|
||||
[](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
|
||||
[](https://www.npmjs.com/package/@xixu-me/skills-vault)
|
||||
|
||||
[](./LICENSE)
|
||||
[](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
|
||||
[](https://bun.sh/)
|
||||
[](./LICENSE)
|
||||
|
||||
`skvlt` snapshots the skills you already have installed into a small YAML manifest, then restores them later by source. It is designed for moving between machines, recovering a setup after reinstalling tools, or checking a team's shared skill baseline into a repo.
|
||||
Skills Vault is a CLI for backing up and restoring [Agent Skills](https://agentskills.io).
|
||||
|
||||
It is built for the common round-trip:
|
||||
|
||||
1. snapshot what is installed today
|
||||
2. commit or move the manifest
|
||||
3. restore the same set of skill sources on another machine
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This package has a Bun-only runtime. Install Bun first, then use `skvlt` through a global install, from source, or from a packed npm tarball.
|
||||
> Bun-only runtime. Skills Vault is designed to be installed and run with Bun.
|
||||
|
||||
## Why Skills Vault?
|
||||
## Why Skills Vault
|
||||
|
||||
- Back up installed skills into a deterministic `skvlt.yaml` manifest.
|
||||
- Restore only missing skills, or reinstall everything from the manifest.
|
||||
- Preserve install scope so global and project-scoped backups round-trip cleanly.
|
||||
- Inspect local health with `doctor` before or after a restore.
|
||||
- Generate shell completion scripts for Bash, Zsh, and PowerShell.
|
||||
- Emit structured JSON for automation and scripting with `--json`.
|
||||
Skills Vault exists to fill the gap described in [vercel-labs/skills#729](https://github.com/vercel-labs/skills/issues/729): a declarative manifest for portable, reproducible skill setups across machines and teams.
|
||||
|
||||
## Getting Started
|
||||
- Back up installed skills into a deterministic `skvlt.yaml` file.
|
||||
- Restore from that manifest by source, by agent, or all at once.
|
||||
- Preview installs before making changes with `--dry-run`.
|
||||
- Check local setup quickly with `doctor`.
|
||||
- Generate completion scripts for `bash`, `zsh`, and `powershell`.
|
||||
|
||||
### Prerequisites
|
||||
## Quick Start
|
||||
|
||||
- [`bun`](https://bun.com) >=1.3.11
|
||||
- Access to the upstream `skills` CLI through `bunx skills`
|
||||
|
||||
### Install
|
||||
Back up your current skills:
|
||||
|
||||
```bash
|
||||
bun add -g @xixu-me/skills-vault@latest
|
||||
bunx skvlt backup
|
||||
```
|
||||
|
||||
Then confirm the CLI is available:
|
||||
Preview what a restore would run:
|
||||
|
||||
```bash
|
||||
skvlt --help
|
||||
skvlt --version
|
||||
bunx skvlt restore --dry-run
|
||||
```
|
||||
|
||||
## Community
|
||||
|
||||
- Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a pull request.
|
||||
- Review [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for participation expectations.
|
||||
- Use [`SUPPORT.md`](./SUPPORT.md) to choose the right support channel.
|
||||
- Follow [`SECURITY.md`](./SECURITY.md) for private vulnerability reporting.
|
||||
|
||||
## Usage
|
||||
|
||||
### 1. Back up installed skills
|
||||
|
||||
Create a manifest for your currently installed skills:
|
||||
Restore everything recorded in the manifest:
|
||||
|
||||
```bash
|
||||
skvlt backup
|
||||
bunx skvlt restore --all
|
||||
```
|
||||
|
||||
Preview the generated YAML without writing a file:
|
||||
If you want a curated, ready-to-use manifest, see [xixu-me/skvlt](https://github.com/xixu-me/skvlt), a maintained collection of `skvlt.yaml` snapshots.
|
||||
|
||||
```bash
|
||||
skvlt backup --dry-run
|
||||
```
|
||||
|
||||
Back up project-scoped installs with an explicit lock file:
|
||||
|
||||
```bash
|
||||
skvlt backup --project-scope --lock-file ./skills-lock.json --output ./skvlt.yaml
|
||||
```
|
||||
|
||||
### 2. Restore from a manifest
|
||||
|
||||
Restore the missing skills recorded in `./skvlt.yaml`:
|
||||
|
||||
```bash
|
||||
skvlt restore
|
||||
```
|
||||
|
||||
Preview the underlying `bunx skills add ...` commands:
|
||||
|
||||
```bash
|
||||
skvlt restore --dry-run
|
||||
```
|
||||
|
||||
Restore only one source:
|
||||
|
||||
```bash
|
||||
skvlt restore --only-source anthropics/skills
|
||||
```
|
||||
|
||||
Target specific agents and copy files instead of symlinking:
|
||||
|
||||
```bash
|
||||
skvlt restore --agent codex --agent claude-code --copy
|
||||
```
|
||||
|
||||
Force a full reinstall from every selected source:
|
||||
|
||||
```bash
|
||||
skvlt restore --reinstall-all
|
||||
```
|
||||
|
||||
Let the upstream source decide the installed skill set:
|
||||
|
||||
```bash
|
||||
skvlt restore --all
|
||||
```
|
||||
|
||||
### 3. Check local state
|
||||
|
||||
Run a quick health check for Bun, the `skills` CLI, your manifest, and global skill consistency:
|
||||
|
||||
```bash
|
||||
skvlt doctor
|
||||
```
|
||||
|
||||
### 4. Enable shell completions
|
||||
|
||||
```bash
|
||||
skvlt completion bash
|
||||
skvlt completion zsh
|
||||
skvlt completion powershell
|
||||
```
|
||||
|
||||
## Manifest Format
|
||||
|
||||
By default, Skills Vault writes `./skvlt.yaml`.
|
||||
The default manifest is `./skvlt.yaml`. A typical file looks like this:
|
||||
|
||||
```yaml
|
||||
total_sources: 2
|
||||
@@ -136,124 +58,142 @@ total_skills: 3
|
||||
scope: "global"
|
||||
|
||||
sources:
|
||||
"anthropics/skills":
|
||||
"alpha/source":
|
||||
count: 1
|
||||
skills:
|
||||
- "beta"
|
||||
|
||||
"beta/source":
|
||||
count: 2
|
||||
skills:
|
||||
- "alpha"
|
||||
- "beta"
|
||||
|
||||
"github/awesome-copilot":
|
||||
count: 1
|
||||
skills:
|
||||
- "gamma"
|
||||
- "zulu"
|
||||
```
|
||||
|
||||
Each source is grouped with the exact skill names seen in the local lock file at backup time. During restore, the manifest scope is respected unless you explicitly override it with `--project-scope`.
|
||||
|
||||
## Commands
|
||||
|
||||
### `backup`
|
||||
|
||||
Capture installed skills into a manifest.
|
||||
Snapshot installed skills into `skvlt.yaml`.
|
||||
|
||||
```text
|
||||
skvlt backup [options]
|
||||
```bash
|
||||
bunx skvlt backup
|
||||
bunx skvlt backup --dry-run
|
||||
bunx skvlt backup --output ./skvlt.yaml
|
||||
bunx skvlt backup --project-scope --lock-file ./skills-lock.json
|
||||
```
|
||||
|
||||
Useful options:
|
||||
`backup` reads installed skill names, joins them with lock-file metadata, and writes a grouped manifest keyed by source.
|
||||
|
||||
- `--output <path>`: write the manifest somewhere other than `./skvlt.yaml`
|
||||
- `--lock-file <path>`: choose which skills lock file to read
|
||||
- `--project-scope`: back up project-scoped installs instead of global installs
|
||||
- `--dry-run`: print the manifest to stdout
|
||||
> [!NOTE]
|
||||
> Global backup reads from `~/.agents/.skill-lock.json` by default. Project-scope backup currently requires `--lock-file`.
|
||||
|
||||
### `restore`
|
||||
|
||||
Recreate a local setup from a manifest.
|
||||
Install skills from a manifest.
|
||||
|
||||
```text
|
||||
skvlt restore [options]
|
||||
```bash
|
||||
bunx skvlt restore --all
|
||||
bunx skvlt restore --only-source xixu-me/skills
|
||||
bunx skvlt restore --project-scope
|
||||
bunx skvlt restore --dry-run
|
||||
```
|
||||
|
||||
Useful options:
|
||||
By default, restore respects the scope recorded in the manifest. Use `--project-scope` to force a project install even when the manifest was created from global state.
|
||||
|
||||
- `--manifest <path>`: restore from a different manifest path
|
||||
- `--only-source <source>`: restore a single source, repeatable
|
||||
- `--agent <agent>`: pass through one or more agent targets
|
||||
- `--copy`: copy files instead of symlinking
|
||||
- `--all`: install all skills from each selected source
|
||||
- `--reinstall-all`: reinstall every skill listed in the manifest
|
||||
- `--continue-on-error`: keep processing later sources after a failure
|
||||
- `--concurrency <count>`: set preview concurrency for dry runs
|
||||
- `--dry-run`: print the generated install commands
|
||||
`--dry-run` prints the derived `bunx skills add ...` commands without running them. Live installs run in lock-safe mode and are serialized to avoid global lock-file races.
|
||||
|
||||
> [!NOTE]
|
||||
> Live restores intentionally serialize installs in lock-safe mode because the upstream `skills` CLI mutates shared global state.
|
||||
For a curated manifest source, you can start from [xixu-me/skvlt](https://github.com/xixu-me/skvlt) and restore from the `skvlt.yaml` maintained there.
|
||||
|
||||
### `doctor`
|
||||
|
||||
Inspect the current environment and skill state.
|
||||
Inspect the local Skills Vault environment and global skill state.
|
||||
|
||||
```text
|
||||
skvlt doctor [options]
|
||||
```bash
|
||||
bunx skvlt doctor
|
||||
bunx skvlt doctor --manifest ./skvlt.yaml
|
||||
```
|
||||
|
||||
Useful options:
|
||||
`doctor` checks:
|
||||
|
||||
- `--manifest <path>`: check a non-default manifest path
|
||||
- the Bun runtime
|
||||
- `bunx skills --help`
|
||||
- whether the manifest exists
|
||||
- whether the global lock file and skills directory are present
|
||||
- whether tracked and installed global skills still match
|
||||
|
||||
### `completion`
|
||||
|
||||
Print a completion script for your shell.
|
||||
Print shell completion scripts.
|
||||
|
||||
```text
|
||||
skvlt completion <bash|zsh|powershell>
|
||||
```bash
|
||||
bunx skvlt completion bash
|
||||
bunx skvlt completion zsh
|
||||
bunx skvlt completion powershell
|
||||
```
|
||||
|
||||
## JSON Output
|
||||
|
||||
Every top-level command accepts `--json`, which makes `skvlt` easier to integrate into scripts and CI:
|
||||
All top-level commands support `--json` for structured output:
|
||||
|
||||
```bash
|
||||
skvlt --json --version
|
||||
skvlt --json backup --dry-run
|
||||
skvlt --json doctor
|
||||
bunx skvlt --json doctor
|
||||
bunx skvlt --json backup --dry-run
|
||||
```
|
||||
|
||||
## Development
|
||||
Successful responses include `ok`, `command`, and `data`. Failures include `ok`, `command`, and a stable `error.code` plus message.
|
||||
|
||||
## Local Development
|
||||
|
||||
Install dependencies:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
bun install --frozen-lockfile
|
||||
```
|
||||
|
||||
Run the main workflows locally:
|
||||
Useful commands:
|
||||
|
||||
```bash
|
||||
bun run format
|
||||
bun run ./src/cli.ts --help
|
||||
bun run ./src/cli.ts doctor
|
||||
bun run backup
|
||||
bun run restore
|
||||
bun run test
|
||||
bun run check
|
||||
```
|
||||
|
||||
Build a publishable tarball:
|
||||
`bun run check` is the main verification gate. It runs formatting checks, the Bun test suite, and `npm pack --dry-run --json`.
|
||||
|
||||
If you change workflow files, also run:
|
||||
|
||||
```bash
|
||||
npm pack
|
||||
bunx prettier --check ".github/**/*.yml"
|
||||
```
|
||||
|
||||
Publish the package:
|
||||
## Package And Release Notes
|
||||
|
||||
The npm package publishes the `skvlt` bin from `src/cli.ts` and intentionally ships the `src` directory as its runtime payload.
|
||||
|
||||
Before publishing, verify the tarball contents locally:
|
||||
|
||||
```bash
|
||||
npm pack --dry-run --json
|
||||
```
|
||||
|
||||
The release workflow uses trusted publishing. The publish step is:
|
||||
|
||||
```bash
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
## Notes
|
||||
## Troubleshooting
|
||||
|
||||
- Global manifests read from `~/.agents/.skill-lock.json` by default.
|
||||
- Global restores verify the relationship between `~/.agents/.skill-lock.json` and `~/.agents/skills`.
|
||||
- Project-scoped backup currently requires `--lock-file` so the source metadata stays explicit.
|
||||
- If restore reports a global state mismatch, inspect `~/.agents/.skill-lock.json` and `~/.agents/skills`.
|
||||
- If environment checks fail, start with `bunx skvlt doctor`.
|
||||
- If packaging checks fail, run `bun run check` and review the tarball output from `npm pack --dry-run --json`.
|
||||
|
||||
For contribution, support, and security policy details, see [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`SUPPORT.md`](./SUPPORT.md), and [`SECURITY.md`](./SECURITY.md).
|
||||
|
||||
## License
|
||||
|
||||
Under the MIT License. See [`LICENSE`](./LICENSE).
|
||||
Licensed under MIT. See [`LICENSE`](./LICENSE).
|
||||
+101
-161
@@ -2,133 +2,55 @@
|
||||
|
||||
**_[English](./README.md)_**
|
||||
|
||||
用于备份和恢复 [Agent Skills](https://agentskills.io) 的 CLI。
|
||||
|
||||
[](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
|
||||
[](https://www.npmjs.com/package/@xixu-me/skills-vault)
|
||||
|
||||
[](./LICENSE)
|
||||
[](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
|
||||
[](https://bun.sh/)
|
||||
[](./LICENSE)
|
||||
|
||||
`skvlt` 会将你已经安装的 skills 快照为一个小型 YAML 清单，然后在之后按来源恢复它们。它适合在多台机器之间迁移、在重装工具后恢复环境，或者将团队共享的 skill 基线纳入存储库管理。
|
||||
Skills Vault 是一个用于备份和恢复 [Agent Skills](https://agentskills.io) 的 CLI。
|
||||
|
||||
它主要服务于这样一个常见流程：
|
||||
|
||||
1. 把当前机器上已安装的 skills 快照出来
|
||||
2. 提交或移动这个 manifest
|
||||
3. 在另一台机器上恢复同一组 skill source
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 这个包只支持 Bun 运行时。请先安装 Bun，然后通过全局安装、源码，或打包后的 npm tarball 使用 `skvlt`。
|
||||
> 仅支持 Bun 运行时。Skills Vault 设计上就是通过 Bun 安装和运行的。
|
||||
|
||||
## 为什么使用 Skills Vault？
|
||||
## 为什么需要 Skills Vault
|
||||
|
||||
- 将已安装的 skills 备份为可确定复现的 `skvlt.yaml` 清单。
|
||||
- 只恢复缺失的 skills，或者按清单完整重装。
|
||||
- 保留安装作用域，让全局安装和项目级安装都能准确往返恢复。
|
||||
- 在恢复前后通过 `doctor` 检查本地环境状态。
|
||||
- 为 Bash、Zsh 和 PowerShell 生成 shell 补全脚本。
|
||||
- 通过 `--json` 输出结构化 JSON，便于自动化和脚本集成。
|
||||
Skills Vault 的存在，是为了补上 [vercel-labs/skills#729](https://github.com/vercel-labs/skills/issues/729) 里提到的缺口：缺少一种声明式 manifest，来支持可移植、可复现的 skills 配置。
|
||||
|
||||
- 把已安装的 skills 备份为确定性的 `skvlt.yaml`
|
||||
- 按 source、按 agent，或者一次性从 manifest 恢复
|
||||
- 通过 `--dry-run` 在真正改动前先预览
|
||||
- 用 `doctor` 快速检查本地环境
|
||||
- 为 `bash`、`zsh` 和 `powershell` 生成补全脚本
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 前置条件
|
||||
|
||||
- [`bun`](https://bun.com) >=1.3.11
|
||||
- 可通过 `bunx skills` 访问上游 `skills` CLI
|
||||
|
||||
### 安装
|
||||
备份当前已安装的 skills：
|
||||
|
||||
```bash
|
||||
bun add -g @xixu-me/skills-vault@latest
|
||||
bunx skvlt backup
|
||||
```
|
||||
|
||||
然后确认 CLI 已可用：
|
||||
预览一次 restore 将会执行什么：
|
||||
|
||||
```bash
|
||||
skvlt --help
|
||||
skvlt --version
|
||||
bunx skvlt restore --dry-run
|
||||
```
|
||||
|
||||
## 社区
|
||||
|
||||
- 在发起 Pull Request 之前先阅读 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。
|
||||
- 参与前请查看 [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)。
|
||||
- 需要支持时请参考 [`SUPPORT.md`](./SUPPORT.md) 选择合适渠道。
|
||||
- 私下报告安全漏洞请遵循 [`SECURITY.md`](./SECURITY.md)。
|
||||
|
||||
## 用法
|
||||
|
||||
### 1. 备份已安装的 skills
|
||||
|
||||
为当前已安装的 skills 创建清单：
|
||||
恢复 manifest 中记录的全部内容：
|
||||
|
||||
```bash
|
||||
skvlt backup
|
||||
bunx skvlt restore --all
|
||||
```
|
||||
|
||||
预览生成的 YAML，而不写入文件：
|
||||
如果你想直接使用一个精选好的 manifest，可以查看 [xixu-me/skvlt](https://github.com/xixu-me/skvlt)，这是一个持续维护的 `skvlt.yaml` 集合。
|
||||
|
||||
```bash
|
||||
skvlt backup --dry-run
|
||||
```
|
||||
|
||||
使用显式锁文件备份项目级安装：
|
||||
|
||||
```bash
|
||||
skvlt backup --project-scope --lock-file ./skills-lock.json --output ./skvlt.yaml
|
||||
```
|
||||
|
||||
### 2. 从清单恢复
|
||||
|
||||
恢复 `./skvlt.yaml` 中记录但当前缺失的 skills：
|
||||
|
||||
```bash
|
||||
skvlt restore
|
||||
```
|
||||
|
||||
预览底层将执行的 `bunx skills add ...` 命令：
|
||||
|
||||
```bash
|
||||
skvlt restore --dry-run
|
||||
```
|
||||
|
||||
只恢复单个来源：
|
||||
|
||||
```bash
|
||||
skvlt restore --only-source anthropics/skills
|
||||
```
|
||||
|
||||
指定 agent，并使用复制而不是符号链接：
|
||||
|
||||
```bash
|
||||
skvlt restore --agent codex --agent claude-code --copy
|
||||
```
|
||||
|
||||
从所有选定来源强制完整重装：
|
||||
|
||||
```bash
|
||||
skvlt restore --reinstall-all
|
||||
```
|
||||
|
||||
让上游来源自行决定要安装哪些 skills：
|
||||
|
||||
```bash
|
||||
skvlt restore --all
|
||||
```
|
||||
|
||||
### 3. 检查本地状态
|
||||
|
||||
快速检查 Bun、`skills` CLI、清单文件，以及全局 skills 一致性：
|
||||
|
||||
```bash
|
||||
skvlt doctor
|
||||
```
|
||||
|
||||
### 4. 启用 shell 补全
|
||||
|
||||
```bash
|
||||
skvlt completion bash
|
||||
skvlt completion zsh
|
||||
skvlt completion powershell
|
||||
```
|
||||
|
||||
## 清单格式
|
||||
|
||||
默认情况下，Skills Vault 会写入 `./skvlt.yaml`。
|
||||
默认 manifest 路径是 `./skvlt.yaml`。一个典型文件如下：
|
||||
|
||||
```yaml
|
||||
total_sources: 2
|
||||
@@ -136,124 +58,142 @@ total_skills: 3
|
||||
scope: "global"
|
||||
|
||||
sources:
|
||||
"anthropics/skills":
|
||||
"alpha/source":
|
||||
count: 1
|
||||
skills:
|
||||
- "beta"
|
||||
|
||||
"beta/source":
|
||||
count: 2
|
||||
skills:
|
||||
- "alpha"
|
||||
- "beta"
|
||||
|
||||
"github/awesome-copilot":
|
||||
count: 1
|
||||
skills:
|
||||
- "gamma"
|
||||
- "zulu"
|
||||
```
|
||||
|
||||
每个来源都会按备份时本地锁文件中看到的精确 skill 名称分组。恢复时会遵循清单中的作用域，除非你显式用 `--project-scope` 覆盖。
|
||||
|
||||
## 命令
|
||||
|
||||
### `backup`
|
||||
|
||||
将已安装的 skills 记录到清单中。
|
||||
把已安装的 skills 快照到 `skvlt.yaml`。
|
||||
|
||||
```text
|
||||
skvlt backup [options]
|
||||
```bash
|
||||
bunx skvlt backup
|
||||
bunx skvlt backup --dry-run
|
||||
bunx skvlt backup --output ./skvlt.yaml
|
||||
bunx skvlt backup --project-scope --lock-file ./skills-lock.json
|
||||
```
|
||||
|
||||
常用选项：
|
||||
`backup` 会先读取已安装的 skill 名称，再结合 lock file 元数据，最终按 source 分组写出 manifest。
|
||||
|
||||
- `--output <path>`：将清单写到 `./skvlt.yaml` 以外的位置
|
||||
- `--lock-file <path>`：指定要读取的 skills 锁文件
|
||||
- `--project-scope`：备份项目级安装，而不是全局安装
|
||||
- `--dry-run`：将清单输出到 stdout
|
||||
> [!NOTE]
|
||||
> 全局备份默认读取 `~/.agents/.skill-lock.json`。项目级备份目前仍然需要显式传入 `--lock-file`。
|
||||
|
||||
### `restore`
|
||||
|
||||
根据清单重建本地环境。
|
||||
从 manifest 安装 skills。
|
||||
|
||||
```text
|
||||
skvlt restore [options]
|
||||
```bash
|
||||
bunx skvlt restore --all
|
||||
bunx skvlt restore --only-source xixu-me/skills
|
||||
bunx skvlt restore --project-scope
|
||||
bunx skvlt restore --dry-run
|
||||
```
|
||||
|
||||
常用选项：
|
||||
默认情况下，`restore` 会遵循 manifest 中记录的 scope。如果希望即使 manifest 来自全局状态，也强制恢复到项目作用域，可以使用 `--project-scope`。
|
||||
|
||||
- `--manifest <path>`：从其他路径的清单恢复
|
||||
- `--only-source <source>`：只恢复单个来源，可重复传入
|
||||
- `--agent <agent>`：透传一个或多个 agent 目标
|
||||
- `--copy`：复制文件而不是创建符号链接
|
||||
- `--all`：从每个选定来源安装全部 skills
|
||||
- `--reinstall-all`：重装清单中列出的所有 skills
|
||||
- `--continue-on-error`：某个来源失败后继续处理后续来源
|
||||
- `--concurrency <count>`：设置 dry run 预览的并发数
|
||||
- `--dry-run`：输出生成的安装命令
|
||||
`--dry-run` 会打印推导出的 `bunx skills add ...` 命令，但不会真正执行。实际安装时会采用 lock-safe 模式串行执行，以避免全局 lock file 竞争。
|
||||
|
||||
> [!NOTE]
|
||||
> 实际恢复会故意以串行方式执行安装，以保证锁文件安全，因为上游 `skills` CLI 会修改共享的全局状态。
|
||||
如果你想从一个精选 manifest 起步，也可以直接使用 [xixu-me/skvlt](https://github.com/xixu-me/skvlt) 中维护的 `skvlt.yaml`。
|
||||
|
||||
### `doctor`
|
||||
|
||||
检查当前环境与 skill 状态。
|
||||
检查本地 Skills Vault 环境和全局 skill 状态。
|
||||
|
||||
```text
|
||||
skvlt doctor [options]
|
||||
```bash
|
||||
bunx skvlt doctor
|
||||
bunx skvlt doctor --manifest ./skvlt.yaml
|
||||
```
|
||||
|
||||
常用选项：
|
||||
`doctor` 会检查：
|
||||
|
||||
- `--manifest <path>`：检查非默认路径的清单
|
||||
- Bun 运行时
|
||||
- `bunx skills --help`
|
||||
- manifest 是否存在
|
||||
- 全局 lock file 和 skills 目录是否存在
|
||||
- lock file 中追踪的技能与实际安装状态是否一致
|
||||
|
||||
### `completion`
|
||||
|
||||
输出当前 shell 的补全脚本。
|
||||
输出 shell 补全脚本。
|
||||
|
||||
```text
|
||||
skvlt completion <bash|zsh|powershell>
|
||||
```bash
|
||||
bunx skvlt completion bash
|
||||
bunx skvlt completion zsh
|
||||
bunx skvlt completion powershell
|
||||
```
|
||||
|
||||
## JSON 输出
|
||||
|
||||
每个顶层命令都支持 `--json`，方便将 `skvlt` 集成进脚本或 CI：
|
||||
所有顶层命令都支持 `--json` 结构化输出：
|
||||
|
||||
```bash
|
||||
skvlt --json --version
|
||||
skvlt --json backup --dry-run
|
||||
skvlt --json doctor
|
||||
bunx skvlt --json doctor
|
||||
bunx skvlt --json backup --dry-run
|
||||
```
|
||||
|
||||
## 开发
|
||||
成功时会返回 `ok`、`command` 和 `data`。失败时会返回 `ok`、`command`，以及稳定的 `error.code` 和错误消息。
|
||||
|
||||
## 本地开发
|
||||
|
||||
安装依赖：
|
||||
|
||||
```bash
|
||||
bun install
|
||||
bun install --frozen-lockfile
|
||||
```
|
||||
|
||||
在本地运行主要工作流：
|
||||
常用命令：
|
||||
|
||||
```bash
|
||||
bun run format
|
||||
bun run ./src/cli.ts --help
|
||||
bun run ./src/cli.ts doctor
|
||||
bun run backup
|
||||
bun run restore
|
||||
bun run test
|
||||
bun run check
|
||||
```
|
||||
|
||||
构建可发布的 tarball：
|
||||
`bun run check` 是主要的发布前校验入口。它会运行格式检查、完整的 Bun 测试，以及 `npm pack --dry-run --json`。
|
||||
|
||||
如果你修改了 workflow 文件，也请额外运行：
|
||||
|
||||
```bash
|
||||
npm pack
|
||||
bunx prettier --check ".github/**/*.yml"
|
||||
```
|
||||
|
||||
发布包：
|
||||
## 打包与发布说明
|
||||
|
||||
npm 包会把 `src/cli.ts` 作为 `skvlt` 可执行入口，并且有意只将 `src` 目录作为运行时载荷发布。
|
||||
|
||||
发布前，可以先在本地检查 tarball 内容：
|
||||
|
||||
```bash
|
||||
npm pack --dry-run --json
|
||||
```
|
||||
|
||||
Release workflow 使用 trusted publishing。实际发布步骤为：
|
||||
|
||||
```bash
|
||||
npm publish --access public
|
||||
```
|
||||
|
||||
## 说明
|
||||
## 故障排查
|
||||
|
||||
- 全局清单默认读取 `~/.agents/.skill-lock.json`。
|
||||
- 全局恢复会校验 `~/.agents/.skill-lock.json` 与 `~/.agents/skills` 之间的关系。
|
||||
- 项目级备份目前需要显式传入 `--lock-file`，以保持来源元数据明确。
|
||||
- 如果 restore 报告全局状态不一致，请检查 `~/.agents/.skill-lock.json` 和 `~/.agents/skills`
|
||||
- 如果环境检查失败，先运行 `bunx skvlt doctor`
|
||||
- 如果打包检查失败，运行 `bun run check`，并检查 `npm pack --dry-run --json` 的输出
|
||||
|
||||
关于贡献、支持和安全策略，请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)、[`SUPPORT.md`](./SUPPORT.md) 和 [`SECURITY.md`](./SECURITY.md)。
|
||||
|
||||
## 许可证
|
||||
|
||||
基于 MIT License 发布。详见 [`LICENSE`](./LICENSE)。
|
||||
基于 MIT 许可证发布。详见 [`LICENSE`](./LICENSE)。
|
||||
+31
-19
@@ -2,35 +2,47 @@
|
||||
|
||||
## Supported Versions
|
||||
|
||||
Security fixes are applied on a best-effort basis to the latest development state on `main` and the latest published package version.
|
||||
Security fixes are handled on a best-effort basis for:
|
||||
|
||||
Older releases may not receive fixes.
|
||||
- the latest published npm release of `@xixu-me/skills-vault`
|
||||
- the current `main` branch in this repository
|
||||
|
||||
Older versions may receive guidance, but they should not be assumed to receive patches.
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
Please do not report security vulnerabilities in public GitHub issues or pull requests.
|
||||
Please do not open public GitHub issues or pull requests for suspected vulnerabilities.
|
||||
|
||||
Instead, report them privately to [email protected]. If GitHub private vulnerability reporting is enabled for this repository, you may use the repository's "Report a vulnerability" flow instead.
|
||||
Preferred reporting path:
|
||||
|
||||
1. Use GitHub Private Vulnerability Reporting for this repository if it is available.
|
||||
2. If private vulnerability reporting is not available, use the private maintainer contact methods listed at [xi-xu.me/contact](https://xi-xu.me/#contact) and clearly label the message as a security report for `skills-vault`.
|
||||
|
||||
Please include:
|
||||
|
||||
- A clear description of the issue
|
||||
- Affected version or commit, if known
|
||||
- Reproduction steps or a proof of concept
|
||||
- Impact assessment, if you have one
|
||||
- Suggested remediation, if available
|
||||
- a description of the issue and impact
|
||||
- affected versions or commit range, if known
|
||||
- reproduction steps or a proof of concept
|
||||
- any suggested remediation, if you already have one
|
||||
|
||||
## What to Expect
|
||||
## Response Expectations
|
||||
|
||||
- We will review reports as quickly as possible.
|
||||
- We may ask follow-up questions to confirm impact and scope.
|
||||
- We will aim for coordinated disclosure and a fix before public discussion.
|
||||
- When appropriate, we will document the fix in a release note or security advisory.
|
||||
This project is maintained on a best-effort basis, but the goal is to:
|
||||
|
||||
## Out of Scope
|
||||
- acknowledge new reports within 5 business days
|
||||
- keep the reporter updated on triage status when material progress is made
|
||||
- coordinate public disclosure after a fix or mitigation is available
|
||||
|
||||
The following are usually not treated as security vulnerabilities by themselves:
|
||||
## Scope
|
||||
|
||||
- Requests for help with local environment setup
|
||||
- Reports that only affect unsupported or heavily modified environments
|
||||
- General dependency hygiene suggestions without a demonstrated impact on this project
|
||||
This policy covers vulnerabilities in this repository, including:
|
||||
|
||||
- CLI command behavior
|
||||
- manifest parsing and install planning
|
||||
- release and packaging configuration in this repository
|
||||
|
||||
If a report only affects an upstream dependency or the external Skills CLI itself, it may need to be reported upstream as well.
|
||||
|
||||
## Security Practices in This Repo
|
||||
|
||||
This repository already uses several baseline security controls, including dependency review automation and locked Bun installs in CI. Additional repository settings such as branch protection, MFA for privileged contributors, and GitHub private vulnerability reporting should stay enabled wherever available.
|
||||
+18
-30
@@ -1,40 +1,28 @@
|
||||
# Support
|
||||
|
||||
Use the right channel so maintainers and contributors can respond efficiently.
|
||||
## Where to Go
|
||||
|
||||
## Bug Reports
|
||||
- Bug reports: open a GitHub issue with the bug report template.
|
||||
- Feature ideas: open a GitHub issue with the feature request template.
|
||||
- Security issues: follow [SECURITY.md](./SECURITY.md) and report them privately.
|
||||
- Contribution questions: read [CONTRIBUTING.md](./CONTRIBUTING.md) first.
|
||||
|
||||
Open a GitHub issue if something is broken, incorrect, or unexpectedly hard to use.
|
||||
## Troubleshooting Checklist
|
||||
|
||||
Include:
|
||||
Before opening an issue, please try:
|
||||
|
||||
- Your platform
|
||||
- Bun version
|
||||
- The command you ran
|
||||
- Expected behavior
|
||||
- Actual behavior
|
||||
- Any logs or reproduction steps
|
||||
```sh
|
||||
bunx skvlt doctor
|
||||
bunx skvlt --help
|
||||
```
|
||||
|
||||
## Feature Requests
|
||||
If the problem is about restoring skills, include:
|
||||
|
||||
Open a GitHub issue for focused feature proposals or product ideas.
|
||||
- the command you ran
|
||||
- whether you used `--dry-run`
|
||||
- whether the manifest was generated from global or project scope
|
||||
- any relevant output from `bunx skvlt doctor`
|
||||
|
||||
Please explain:
|
||||
## Response Expectations
|
||||
|
||||
- The problem you are trying to solve
|
||||
- Why the current behavior is not enough
|
||||
- What outcome you want
|
||||
|
||||
## Usage Questions
|
||||
|
||||
If you are unsure whether something is a bug, you can still open a GitHub issue and describe the question clearly. Add as much context as you can so it can be triaged quickly.
|
||||
|
||||
## Security Reports
|
||||
|
||||
For security issues, do not use public issues.
|
||||
|
||||
Follow the process in [SECURITY.md](./SECURITY.md).
|
||||
|
||||
## Contribution Process
|
||||
|
||||
For setup, tests, pull requests, and contribution expectations, see [CONTRIBUTING.md](./CONTRIBUTING.md).
|
||||
This project is maintained on a best-effort basis. Clear reproduction steps, example manifests, and exact command output make it much easier to help quickly.
|
||||
+2
-2
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "@xixu-me/skills-vault",
|
||||
"version": "1.0.1",
|
||||
"description": "The CLI for backing up and restoring Agent Skills.",
|
||||
"version": "0.9.9",
|
||||
"description": "The CLI for backing up and restoring Agent Skills",
|
||||
"author": "Xi Xu",
|
||||
"bin": {
|
||||
"skvlt": "src/cli.ts"
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
import { expect, test } from "bun:test";
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { resolve } from "node:path";
|
||||
|
||||
const repoRoot = resolve(import.meta.dir, "..");
|
||||
|
||||
test("ships core open source community files", () => {
|
||||
const requiredFiles = [
|
||||
"README.md",
|
||||
"CONTRIBUTING.md",
|
||||
"CODE_OF_CONDUCT.md",
|
||||
"SECURITY.md",
|
||||
"SUPPORT.md",
|
||||
".github/ISSUE_TEMPLATE/bug_report.yml",
|
||||
".github/ISSUE_TEMPLATE/feature_request.yml",
|
||||
".github/ISSUE_TEMPLATE/config.yml",
|
||||
".github/PULL_REQUEST_TEMPLATE.md",
|
||||
];
|
||||
|
||||
for (const relativePath of requiredFiles) {
|
||||
expect(existsSync(resolve(repoRoot, relativePath))).toBe(true);
|
||||
}
|
||||
});
|
||||
|
||||
test("readme links contributors to project, support, and security guidance", () => {
|
||||
const readme = readFileSync(resolve(repoRoot, "README.md"), "utf8");
|
||||
|
||||
expect(readme).toContain("# Skills Vault");
|
||||
expect(readme).toContain("Bun-only runtime");
|
||||
expect(readme).toContain("CONTRIBUTING.md");
|
||||
expect(readme).toContain("SUPPORT.md");
|
||||
expect(readme).toContain("SECURITY.md");
|
||||
});
|
||||
@@ -47,6 +47,5 @@ test("includes a publishable readme that documents the Bun runtime", () => {
|
||||
const readme = readFileSync(readmePath, "utf8");
|
||||
expect(readme).toContain("Skills Vault");
|
||||
expect(readme).toContain("Bun-only runtime");
|
||||
expect(readme).toContain("bun add -g @xixu-me/skills-vault@latest");
|
||||
expect(readme).toContain("npm publish --access public");
|
||||
});
|
||||
Reference in new issue
Block a user