xixu-me/skills-vault
1
0 Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(release): prepare v1.0.0

Browse Source
This commit is contained in:
xixu-me committed 2026-03-25 21:43:09 +08:00
1 parent 579101a440
commit 5522dbb326
11 files changed
+543 -69
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/ISSUE_TEMPLATE/bug_report.yml
+54
View File
@@ -0,0 +1,54 @@
name: Bug report
description: Report a reproducible bug or regression
title: "[Bug]: "
labels:
- bug
body:
- type: markdown
attributes:
value: |
Thanks for reporting a bug. Please include enough detail for someone else to reproduce it.
- type: input
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 ...
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
validations:
required: true
- type: textarea
id: environment
attributes:
label: Environment
description: OS, shell, Bun version, package version, and anything else relevant
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logs or screenshots
description: Paste relevant output here
render: shell
.github/ISSUE_TEMPLATE/config.yml
+8
View File
@@ -0,0 +1,8 @@
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.
.github/ISSUE_TEMPLATE/feature_request.yml
+30
View File
@@ -0,0 +1,30 @@
name: Feature request
description: Propose a focused improvement to the CLI or developer workflow
title: "[Feature]: "
labels:
- enhancement
body:
- type: textarea
id: problem
attributes:
label: Problem to solve
description: What user problem or workflow gap are you seeing?
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed change
description: Describe the behavior you want
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: What workarounds or alternative designs did you consider?
- type: textarea
id: context
attributes:
label: Additional context
description: Examples, prior art, links, or constraints
.github/ISSUE_TEMPLATE/question.yml
+32
View File
@@ -0,0 +1,32 @@
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
.github/PULL_REQUEST_TEMPLATE.md
+21
View File
@@ -0,0 +1,21 @@
## Summary
- What changed?
- Why is this change needed?
## Verification
- [ ] `bun run test`
- [ ] `bun run check`
Describe any manual verification you performed:
## 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.
CODE_OF_CONDUCT.md
+50
View File
@@ -0,0 +1,50 @@
# Code of Conduct
## Our Commitment
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.
## Expected Behavior
Examples of behavior that help build a healthy community include:
- 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
## Unacceptable Behavior
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
## 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
## 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.
Retaliation against anyone who reports a concern in good faith is not acceptable.
CONTRIBUTING.md
+93
View File
@@ -0,0 +1,93 @@
# Contributing to Skills Vault
Thanks for your interest in contributing to Skills Vault.
This project is a Bun-based CLI for backing up and restoring agent skills. We welcome bug reports, documentation improvements, tests, and focused feature proposals.
## 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.
## Ways to Contribute
- Report bugs
- Improve documentation
- Add or improve tests
- Propose targeted CLI improvements
- Fix small usability issues or polish error messages
If you plan to work on a larger change, open an issue first so we can agree on scope before implementation starts.
## Development Setup
Prerequisites:
- Bun `>=1.3.11`
Install dependencies:
```bash
bun install
```
Useful commands:
```bash
bun run format
bun run test
bun run check
```
## Contribution Workflow
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.
## Pull Request Guidelines
Good pull requests are:
- Small and focused
- Clear about user impact
- Covered by tests when behavior changes
- Updated to match the current CLI behavior and docs
Please include:
- What changed
- Why it changed
- How you verified it
- Any follow-up work or known limitations
## Reporting Bugs
Open a GitHub issue with:
- Your environment
- The command you ran
- Expected behavior
- Actual behavior
- Logs or screenshots when relevant
- A small reproduction, if possible
## Feature Requests
Feature requests are welcome, especially when they are:
- Clearly scoped
- Tied to a concrete user problem
- Consistent with the project's CLI-first design
## 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.
README.md
+178 -68
View File
@@ -1,80 +1,128 @@
# Skills Vault
`skvlt` is a Bun-powered CLI for backing up and restoring agent skills from the upstream `skills` ecosystem.
CLI for backing up and restoring agent skills.
It is published on npm for distribution, but it is intentionally a Bun-only runtime today. Users install it from npm and run it with Bun available on their machine.
[![CI](https://img.shields.io/github/actions/workflow/status/xixu-me/skills-vault/ci.yml?label=CI)](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40xixu-me%2Fskills-vault)](https://www.npmjs.com/package/@xixu-me/skills-vault)
![Bun](https://img.shields.io/badge/Bun-%3E%3D1.3.11-f9f1e1)
[![License](https://img.shields.io/badge/License-MIT-blue)](./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.
> [!IMPORTANT]
> `skvlt` currently requires Bun `>=1.3.11`.
> The npm package installs cleanly, but the CLI itself is executed through Bun.
> 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.
## What It Does
## Why Skills Vault?
- Back up installed skills into a portable `skvlt.yaml` manifest
- Restore skills from a saved manifest
- Inspect the local runtime and skill state with `doctor`
- Print shell completion scripts for `bash`, `zsh`, and `powershell`
- 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`.
## Install
## Getting Started
Install Bun first:
### Prerequisites
```bash
bun --version
```
- [Bun](https://bun.com) `>=1.3.11`
- Access to the upstream `skills` CLI through `bunx skills`
Then install the CLI from npm:
### Install
```bash
npm install -g @xixu-me/skills-vault
```
Verify the install:
Or with Bun:
```bash
bun add -g @xixu-me/skills-vault@latest
```
Then confirm the CLI is available:
```bash
skvlt --version
skvlt --help
skvlt --version
```
You can also run the package without a global install:
## Community
```bash
npx @xixu-me/skills-vault --help
```
- 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.
## Quick Start
## Usage
Back up global skills into `./skvlt.yaml`:
### 1. Back up installed skills
Create a manifest for your currently installed skills:
```bash
skvlt backup
```
Preview a backup without writing files:
Preview the generated YAML without writing a file:
```bash
skvlt backup --dry-run
```
Restore missing skills from a manifest:
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 restore commands first:
Preview the underlying `bunx skills add ...` commands:
```bash
skvlt restore --dry-run
```
Inspect your environment:
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
```
Generate shell completions:
### 4. Enable shell completions
```bash
skvlt completion bash
@@ -82,72 +130,134 @@ skvlt completion zsh
skvlt completion powershell
```
## Manifest Format
By default, Skills Vault writes `./skvlt.yaml`.
```yaml
total_sources: 2
total_skills: 3
scope: "global"
sources:
"anthropics/skills":
count: 2
skills:
- "alpha"
- "beta"
"github/awesome-copilot":
count: 1
skills:
- "gamma"
```
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
### `skvlt backup`
### `backup`
Creates a manifest snapshot of installed skills.
Capture installed skills into a manifest.
Common options:
```text
skvlt backup [options]
```
- `--output <path>`: write the manifest to a custom path
- `--lock-file <path>`: read source metadata from a specific lock file
Useful options:
- `--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 instead of writing a file
- `--dry-run`: print the manifest to stdout
By default, the manifest is written to `./skvlt.yaml`.
### `restore`
### `skvlt restore`
Recreate a local setup from a manifest.
Restores skills from a manifest and uses the upstream `skills` CLI through `bunx`.
```text
skvlt restore [options]
```
Common options:
Useful options:
- `--manifest <path>`: read a custom manifest path
- `--only-source <source>`: restore just one source, repeatable
- `--agent <agent>`: target one agent, repeatable
- `--project-scope`: restore to project scope instead of global scope
- `--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 for selected sources
- `--reinstall-all`: reinstall everything even if already present
- `--continue-on-error`: keep restoring after one source fails
- `--concurrency <count>`: control parallel source installs
- `--dry-run`: print the derived `bunx` commands instead of running them
- `--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
### `skvlt doctor`
> [!NOTE]
> Live restores intentionally serialize installs in lock-safe mode because the upstream `skills` CLI mutates shared global state.
Reports the local Bun runtime, upstream `skills` CLI availability, manifest presence, and global skill state consistency.
### `doctor`
### `skvlt completion`
Inspect the current environment and skill state.
Prints completion scripts for:
```text
skvlt doctor [options]
```
- `bash`
- `zsh`
- `powershell`
Useful options:
## Runtime Notes
- `--manifest <path>`: check a non-default manifest path
- Global manifests default to `./skvlt.yaml`
- Global restore verification checks `~/.agents/skills`
- Global lock-file checks use `~/.agents/.skill-lock.json`
- `restore` and `doctor` rely on the upstream `skills` CLI being reachable via `bunx`
### `completion`
## Publishing
Print a completion script for your shell.
This project is distributed through npm and exposed as the CLI command `skvlt`.
```text
skvlt completion <bash|zsh|powershell>
```
Recommended release flow:
## JSON Output
Every top-level command accepts `--json`, which makes `skvlt` easier to integrate into scripts and CI:
```bash
skvlt --json --version
skvlt --json backup --dry-run
skvlt --json doctor
```
## Development
Install dependencies:
```bash
bun install
```
Run the main workflows locally:
```bash
bun run format
bun run test
bun run check
npm pack --dry-run --json
```
Build a publishable tarball:
```bash
npm pack
```
Publish the package:
```bash
npm publish --access public
```
For a safer pre-publish smoke test, install the generated tarball into a temporary prefix and run:
## Notes
```bash
skvlt --help
skvlt --version
```
- 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.
## License
Under the MIT License. See [`LICENSE`](./LICENSE).
SECURITY.md
+36
View File
@@ -0,0 +1,36 @@
# Security Policy
## Supported Versions
Security fixes are applied on a best-effort basis to the latest development state on `main` and the latest published package version.
Older releases may not receive fixes.
## Reporting a Vulnerability
Please do not report security vulnerabilities in public GitHub issues or pull requests.
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.
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
## What to Expect
- 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.
## Out of Scope
The following are usually not treated as security vulnerabilities by themselves:
- 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
SUPPORT.md
+40
View File
@@ -0,0 +1,40 @@
# Support
Use the right channel so maintainers and contributors can respond efficiently.
## Bug Reports
Open a GitHub issue if something is broken, incorrect, or unexpectedly hard to use.
Include:
- Your platform
- Bun version
- The command you ran
- Expected behavior
- Actual behavior
- Any logs or reproduction steps
## Feature Requests
Open a GitHub issue for focused feature proposals or product ideas.
Please explain:
- 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).
package.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@xixu-me/skills-vault",
"version": "0.1.0",
"version": "1.0.0",
"description": "CLI for backing up and restoring agent skills.",
"author": "Xi Xu",
"bin": {