@hagicode/skillsbase

中文文档

skillsbase is a standalone Node.js CLI for bootstrapping and maintaining managed skills repositories. It ships the CLI and templates only. The generated skills/ content belongs in the target repository, not in this package repository.

Install

Requirements:

• Node.js >= 22.12.0
• npm >= 10.9.2

Install globally:

npm install --global @hagicode/skillsbase

Then run:

skillsbase --help

Quick Start

Initialize a managed repository:

skillsbase init --repo /path/to/target-repo

Sync managed skills from sources.yaml:

skillsbase sync --repo /path/to/target-repo

Add one skill and sync immediately:

skillsbase add documentation-writer --repo /path/to/target-repo

Remove one skill and sync immediately:

skillsbase remove documentation-writer --repo /path/to/target-repo

Generate managed GitHub Actions assets:

skillsbase github_action --repo /path/to/target-repo --kind all

Commands

Command	Purpose	Example
init	Create the managed repository baseline.	skillsbase init --repo ./my-skills-repo
sync	Reconcile managed skills from sources.yaml.	skillsbase sync --repo ./my-skills-repo
sync --check	Validate drift without writing files.	skillsbase sync --check --repo ./my-skills-repo
add <skill-name>	Add a skill to a source block, then run sync.	skillsbase add documentation-writer --repo ./my-skills-repo
remove <skill-name>	Remove a skill from a source block, then run sync.	skillsbase remove documentation-writer --repo ./my-skills-repo
github_action	Generate managed GitHub Actions workflow or action files.	skillsbase github_action --repo ./my-skills-repo --kind workflow

Global options:

• --repo <path>: target repository path, defaults to the current directory
• --help, -h: show help
• --version, -v: show version

Managed Repository Contract

skillsbase manages files in the target repository, including:

• sources.yaml: the single source of truth for source roots, naming rules, include lists, and defaults
• skills/<name>/SKILL.md: managed skill output converted from installed source content
• skills/<name>/.skill-source.json: source, conversion, target-path, and install metadata
• docs/maintainer-workflow.md: maintainer guidance generated from the bundled templates
• .github/workflows/skills-sync.yml: reusable workflow for validation and sync checks
• .github/actions/skillsbase-sync/action.yml: reusable composite action

Non-Interactive Defaults

• The target repository defaults to the current working directory.
• init defaults the source roots to:
  • first-party: $HOME/.agents/skills
  • system: $HOME/.codex/skills/.system
• add writes to the first declared source block unless --source <key> is provided.
• remove deletes from the only matching source block automatically; if multiple source blocks include the same skill, pass --source <key>.
• add, remove, and sync accept --allow-missing-sources to keep path-resolution behavior consistent in CI or repo-external execution.
• github_action defaults to --kind workflow.
• When the CLI does not have enough context to write safely, it fails with diagnostics instead of prompting interactively.

Development

Common commands for working on this package:

npm run build
npm run cli -- --help
npm test
npm run smoke
npm run pack:check

The published entry point is bin/skillsbase.mjs. In development, npm run cli -- <args> runs the TypeScript entry directly.

Publishing Notes

The GitHub Actions workflow supports two npm authentication modes:

• Preferred: npm trusted publishing via GitHub Actions OIDC
• Fallback: NPM_TOKEN repository secret mapped to NODE_AUTH_TOKEN

Before relying on trusted publishing, make sure the npm package settings for @hagicode/skillsbase trust the HagiCode-org/skillsbase repository. The npm docs currently require Node.js >= 22.14.0 and npm >= 11.5.1 for trusted publishing.