agent-skillboard 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +83 -0
- package/LICENSE +21 -0
- package/README.md +645 -0
- package/bin/skillboard.mjs +4 -0
- package/docs/adapters.md +127 -0
- package/docs/capabilities.md +107 -0
- package/docs/install.md +346 -0
- package/docs/plans/20260625-080025-skillboard-mvp-review.md +189 -0
- package/docs/plans/README.md +20 -0
- package/docs/policy-model.md +251 -0
- package/docs/positioning.md +94 -0
- package/docs/profiles.md +166 -0
- package/docs/rollout-runbook.md +60 -0
- package/docs/user-flow.md +231 -0
- package/docs/versioning.md +201 -0
- package/examples/multi-source-skills/anthropic/docx/SKILL.md +8 -0
- package/examples/multi-source-skills/anthropic/skill-creator/SKILL.md +8 -0
- package/examples/multi-source-skills/matt/grill-me/SKILL.md +8 -0
- package/examples/multi-source-skills/matt/tdd/SKILL.md +8 -0
- package/examples/multi-source-skills/omo/review-work/SKILL.md +8 -0
- package/examples/multi-source-skills/omo/ulw-plan/SKILL.md +8 -0
- package/examples/multi-source-skills/private/tdd-work-continuity/SKILL.md +8 -0
- package/examples/multi-source-skills/private/workflow-router/SKILL.md +8 -0
- package/examples/multi-source-skills/wshobson/python-testing/SKILL.md +8 -0
- package/examples/multi-source-skills/wshobson/security-review/SKILL.md +8 -0
- package/examples/multi-source.config.yaml +271 -0
- package/examples/skillboard.config.yaml +194 -0
- package/examples/skills/grill-me/SKILL.md +9 -0
- package/examples/skills/grill-with-docs/SKILL.md +9 -0
- package/examples/skills/requirement-intake/SKILL.md +9 -0
- package/examples/skills/tdd/SKILL.md +8 -0
- package/package.json +58 -0
- package/profiles/anthropics-skills.yaml +17 -0
- package/profiles/mattpocock-skills.yaml +26 -0
- package/profiles/oh-my-openagent.yaml +32 -0
- package/profiles/voltagent-awesome-agent-skills.yaml +18 -0
- package/profiles/wshobson-agents.yaml +19 -0
- package/src/advisor/action-core.mjs +74 -0
- package/src/advisor/actions.mjs +256 -0
- package/src/advisor/application-commands.mjs +59 -0
- package/src/advisor/apply-action.mjs +183 -0
- package/src/advisor/schema.mjs +112 -0
- package/src/advisor/setup-actions.mjs +42 -0
- package/src/advisor/skills.mjs +191 -0
- package/src/advisor/sort.mjs +15 -0
- package/src/advisor/sources.mjs +160 -0
- package/src/advisor/trust-policy.mjs +65 -0
- package/src/advisor/workflow.mjs +41 -0
- package/src/advisor.mjs +134 -0
- package/src/agent-inventory-platforms.mjs +100 -0
- package/src/agent-inventory.mjs +804 -0
- package/src/brief-cli.mjs +40 -0
- package/src/brief-renderer.mjs +362 -0
- package/src/change-plan.mjs +169 -0
- package/src/cli.mjs +1171 -0
- package/src/config-helpers.mjs +72 -0
- package/src/control/can-use-guard.mjs +91 -0
- package/src/control/config-write.mjs +163 -0
- package/src/control/skill-crud.mjs +394 -0
- package/src/control/source-trust.mjs +161 -0
- package/src/control/workflow-crud.mjs +104 -0
- package/src/control.mjs +197 -0
- package/src/doctor.mjs +299 -0
- package/src/domain/constants.mjs +47 -0
- package/src/domain/indexes.mjs +29 -0
- package/src/domain/rules/capabilities.mjs +33 -0
- package/src/domain/rules/harnesses.mjs +16 -0
- package/src/domain/rules/install-units.mjs +95 -0
- package/src/domain/rules/skills.mjs +105 -0
- package/src/domain/rules/workflows.mjs +105 -0
- package/src/domain/skill-state-matrix.mjs +79 -0
- package/src/domain/source-classes.mjs +99 -0
- package/src/hook-plan.mjs +152 -0
- package/src/impact.mjs +41 -0
- package/src/index.mjs +82 -0
- package/src/init.mjs +136 -0
- package/src/install-output-detector.mjs +337 -0
- package/src/install-units.mjs +62 -0
- package/src/inventory-refresh.mjs +45 -0
- package/src/lifecycle-cli.mjs +166 -0
- package/src/lifecycle-content.mjs +87 -0
- package/src/policy.mjs +42 -0
- package/src/reconcile.mjs +111 -0
- package/src/report.mjs +151 -0
- package/src/review.mjs +88 -0
- package/src/rollout.mjs +453 -0
- package/src/skill-paths.mjs +17 -0
- package/src/source-cache.mjs +178 -0
- package/src/source-profile-loader.mjs +160 -0
- package/src/source-profiles.mjs +299 -0
- package/src/source-verification.mjs +252 -0
- package/src/uninstall.mjs +258 -0
- package/src/workspace.mjs +219 -0
- package/tsconfig.lsp.json +15 -0
package/docs/profiles.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Source Profiles
|
|
2
|
+
|
|
3
|
+
SkillBoard imports skill repositories through **source profiles**. A profile is a YAML file that tells SkillBoard how to find `SKILL.md` files in a source tree and how to classify the skills it finds, without writing repository-specific code.
|
|
4
|
+
|
|
5
|
+
## Why Profiles Exist
|
|
6
|
+
|
|
7
|
+
Agent skill repositories come in many layouts:
|
|
8
|
+
|
|
9
|
+
- `skills/<category>/<skill>/SKILL.md`
|
|
10
|
+
- `<skill>/SKILL.md`
|
|
11
|
+
- deprecated or in-progress folders with special rules
|
|
12
|
+
- namespaces such as `matt.tdd` or `anthropic.requirement-intake`
|
|
13
|
+
|
|
14
|
+
Instead of hardcoding `if (repo === "mattpocock/skills")` branches, SkillBoard reads a declarative profile. The same importer code works for every source.
|
|
15
|
+
|
|
16
|
+
## Profile Location
|
|
17
|
+
|
|
18
|
+
Built-in profiles ship with the CLI under `profiles/`:
|
|
19
|
+
|
|
20
|
+
- `profiles/mattpocock-skills.yaml`
|
|
21
|
+
- `profiles/anthropics-skills.yaml`
|
|
22
|
+
- `profiles/oh-my-openagent.yaml`
|
|
23
|
+
- `profiles/wshobson-agents.yaml`
|
|
24
|
+
- `profiles/voltagent-awesome-agent-skills.yaml`
|
|
25
|
+
|
|
26
|
+
Project-specific profiles can live under `.skillboard/profiles/`:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
skillboard import --profile .skillboard/profiles/my-team.yaml --source-root /path/to/repo
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Profile YAML Structure
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
id: github.mattpocock.skills
|
|
36
|
+
source: mattpocock/skills
|
|
37
|
+
kind: marketplace
|
|
38
|
+
namespace: matt
|
|
39
|
+
target_path_prefix: matt
|
|
40
|
+
scope: user-global
|
|
41
|
+
default_status: vendor
|
|
42
|
+
default_invocation: manual-only
|
|
43
|
+
default_exposure: exported
|
|
44
|
+
default_category: uncategorized
|
|
45
|
+
category_path_segment: 1
|
|
46
|
+
skill_paths:
|
|
47
|
+
- "skills/**/SKILL.md"
|
|
48
|
+
- "*/SKILL.md"
|
|
49
|
+
path_rules:
|
|
50
|
+
- pattern: "skills/deprecated/**/SKILL.md"
|
|
51
|
+
status: deprecated
|
|
52
|
+
invocation: deprecated
|
|
53
|
+
category: deprecated
|
|
54
|
+
- pattern: "skills/in-progress/**/SKILL.md"
|
|
55
|
+
status: candidate
|
|
56
|
+
category: in-progress
|
|
57
|
+
provided_components:
|
|
58
|
+
- skills
|
|
59
|
+
permission_risk: medium
|
|
60
|
+
rollback: reinstall
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Fields
|
|
64
|
+
|
|
65
|
+
| Field | Required | Description |
|
|
66
|
+
|-------|----------|-------------|
|
|
67
|
+
| `id` | yes | Unique install-unit id used in `skillboard.config.yaml`. |
|
|
68
|
+
| `source` | no | Human-readable source identifier, e.g. `owner/repo` or install command. |
|
|
69
|
+
| `kind` | yes | One of the install-unit kinds: `skill`, `plugin`, `marketplace`, `harness`, `mcp-server`, `hook`, `agent`, `lsp`. |
|
|
70
|
+
| `namespace` | no | Prefix added to every generated skill id. Empty means use the bare slug. |
|
|
71
|
+
| `target_path_prefix` | no | Prefix added to every generated skill `path`. |
|
|
72
|
+
| `scope` | no | Install scope: `user-global`, `project`, `local`, `admin`. |
|
|
73
|
+
| `default_status` | no | Default skill `status`: `discovered`, `vendor`, `candidate`, `active`, `quarantined`, `blocked`, `deprecated`, etc. |
|
|
74
|
+
| `default_invocation` | no | Default `invocation`: `manual-only`, `router-only`, `workflow-auto`, `blocked`, `deprecated`. `global-auto` is downgraded to `blocked`. |
|
|
75
|
+
| `default_exposure` | no | Default `exposure`: `exported`, `global-meta`, `unit-managed`, `private`. |
|
|
76
|
+
| `default_category` | no | Fallback category when no path rule or segment applies. |
|
|
77
|
+
| `category_path_segment` | no | Reads a path segment from the matched `SKILL.md` path as category. `skills/engineering/tdd/SKILL.md` with segment `1` becomes `engineering`. |
|
|
78
|
+
| `skill_paths` | yes | Glob patterns that identify `SKILL.md` files to import. |
|
|
79
|
+
| `path_rules` | no | First-match overrides for paths such as `deprecated/**` or `in-progress/**`. |
|
|
80
|
+
| `provided_components` | no | Components supplied by the install unit: `skills`, `commands`, `hooks`, `mcp_servers`. |
|
|
81
|
+
| `permission_risk` | no | `low`, `medium`, `high`. |
|
|
82
|
+
| `rollback` | no | Rollback strategy hint. |
|
|
83
|
+
|
|
84
|
+
## How to Add a Built-In Profile
|
|
85
|
+
|
|
86
|
+
1. **Create `profiles/<short-name>.yaml`.**
|
|
87
|
+
|
|
88
|
+
Pick a short, descriptive file name. The `id` field should be a stable dotted identifier.
|
|
89
|
+
|
|
90
|
+
2. **Choose defaults that keep imported skills inactive.**
|
|
91
|
+
|
|
92
|
+
New external skills should default to `vendor` or `candidate` with `manual-only` or `router-only` invocation. Do not use `global-auto` for external repositories.
|
|
93
|
+
|
|
94
|
+
3. **Add `path_rules` for repository conventions.**
|
|
95
|
+
|
|
96
|
+
If the repo has `deprecated/`, `in-progress/`, or `archive/` folders, override status and invocation there.
|
|
97
|
+
|
|
98
|
+
4. **Test the profile against a real or fixture source.**
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
skillboard import \
|
|
102
|
+
--profile github.myorg.skills \
|
|
103
|
+
--source-root /path/to/myorg-skills \
|
|
104
|
+
--out .skillboard/reports/myorg-import.yaml
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Review the emitted fragment before merging.
|
|
108
|
+
|
|
109
|
+
5. **Add an integration test.**
|
|
110
|
+
|
|
111
|
+
Put a minimal fixture under `test/fixtures/` or `examples/` and add a test in `test/source-profiles.test.mjs` or `test/multi-source-integration.test.mjs`.
|
|
112
|
+
|
|
113
|
+
6. **Update `package.json` `files` if needed.**
|
|
114
|
+
|
|
115
|
+
Profiles are already included via `"files": [..., "profiles", ...]`.
|
|
116
|
+
|
|
117
|
+
## Example Walkthrough
|
|
118
|
+
|
|
119
|
+
Given this repository layout:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
myorg-skills/
|
|
123
|
+
engineering/
|
|
124
|
+
tdd/
|
|
125
|
+
SKILL.md
|
|
126
|
+
review/
|
|
127
|
+
SKILL.md
|
|
128
|
+
deprecated/
|
|
129
|
+
old-linter/
|
|
130
|
+
SKILL.md
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
and this profile:
|
|
134
|
+
|
|
135
|
+
```yaml
|
|
136
|
+
id: github.myorg.skills
|
|
137
|
+
source: myorg/skills
|
|
138
|
+
kind: marketplace
|
|
139
|
+
namespace: myorg
|
|
140
|
+
target_path_prefix: myorg
|
|
141
|
+
scope: user-global
|
|
142
|
+
default_status: vendor
|
|
143
|
+
default_invocation: manual-only
|
|
144
|
+
default_exposure: exported
|
|
145
|
+
category_path_segment: 0
|
|
146
|
+
skill_paths:
|
|
147
|
+
- "**/SKILL.md"
|
|
148
|
+
path_rules:
|
|
149
|
+
- pattern: "deprecated/**/SKILL.md"
|
|
150
|
+
status: deprecated
|
|
151
|
+
invocation: deprecated
|
|
152
|
+
category: deprecated
|
|
153
|
+
provided_components:
|
|
154
|
+
- skills
|
|
155
|
+
permission_risk: medium
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
SkillBoard produces:
|
|
159
|
+
|
|
160
|
+
- `myorg.tdd` → path `myorg/tdd`, category `engineering`, status `vendor`, invocation `manual-only`
|
|
161
|
+
- `myorg.review` → path `myorg/review`, category `engineering`
|
|
162
|
+
- `myorg.old-linter` → path `myorg/old-linter`, category `deprecated`, status `deprecated`, invocation `deprecated`
|
|
163
|
+
|
|
164
|
+
## When to Use a Detector Instead
|
|
165
|
+
|
|
166
|
+
Profiles cover most repository layouts. If a source mutates config files, exposes components only through command output, or requires parsing a non-YAML manifest, use `skillboard inventory detect` or write a small detector. See [adapters.md](adapters.md) for the adapter/detector model.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# SkillBoard Rollout Runbook
|
|
2
|
+
|
|
3
|
+
Use this runbook when SkillBoard is operated as an enterprise rollout gate for agent skills, plugins, harnesses, hooks, MCP servers, and workflow bundles.
|
|
4
|
+
|
|
5
|
+
## Preconditions
|
|
6
|
+
|
|
7
|
+
- Run on Node.js 20 or newer.
|
|
8
|
+
- Keep `skillboard.config.yaml` as the source of truth.
|
|
9
|
+
- Use `--json` for automation; rollout commands do not prompt or wait for user input.
|
|
10
|
+
- Treat plugin, runtime extension, and external package sources as blocked from automatic activation unless an explicit reviewed/trusted policy is recorded in config.
|
|
11
|
+
|
|
12
|
+
## Status and exit codes
|
|
13
|
+
|
|
14
|
+
- `healthy`: exit code `0`; policy and source gates passed.
|
|
15
|
+
- `safe-mode`: exit code `1`; reserved for usable-but-limited rollout states.
|
|
16
|
+
- `strict-failed`: exit code `2`; policy/source gates failed and automation must not apply rollout.
|
|
17
|
+
- `apply-failed`: exit code `3`; apply was blocked or failed before a committed transaction.
|
|
18
|
+
- `rollback-needed`: exit code `4`; apply failed after mutation risk and operator rollback is required.
|
|
19
|
+
|
|
20
|
+
## Standard rollout flow
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
skillboard rollout audit --config skillboard.config.yaml --skills skills --json
|
|
24
|
+
skillboard rollout plan --config skillboard.config.yaml --skills skills --json
|
|
25
|
+
skillboard rollout apply --config skillboard.config.yaml --skills skills --json
|
|
26
|
+
skillboard rollout report --config skillboard.config.yaml --skills skills --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`audit` and `plan` are read-only. `apply` creates a transaction directory under `.skillboard/rollouts/` with a manifest, report, state file, and exact-byte backup of the config before committing.
|
|
30
|
+
|
|
31
|
+
## Source gate policy
|
|
32
|
+
|
|
33
|
+
Rollout blocks unreviewed high-risk runtime/plugin/external sources when they could become active through model-selectable skills. Before apply, review each relevant install unit and set a reviewed/trusted trust level only after source ownership, pinning, and expected runtime components are understood.
|
|
34
|
+
|
|
35
|
+
## Emergency rollback
|
|
36
|
+
|
|
37
|
+
If a rollout report or operator check indicates `rollback-needed`, restore the committed transaction by id:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
skillboard rollout rollback \
|
|
41
|
+
--config skillboard.config.yaml \
|
|
42
|
+
--skills skills \
|
|
43
|
+
--transaction rollout-YYYYMMDDHHMMSS \
|
|
44
|
+
--json
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Rollback reads `.skillboard/rollouts/<transaction>/manifest.json` and restores configured files from their recorded backups. The config restore is byte-for-byte so accidental operator edits made after apply are removed.
|
|
48
|
+
|
|
49
|
+
## Fleet report handling
|
|
50
|
+
|
|
51
|
+
Use `skillboard rollout report --json` for dashboards and schedulers. The report includes deterministic status counters for `healthy`, `safe-mode`, `strict-failed`, `apply-failed`, and `rollback-needed`. Local paths and obvious secret/token values are redacted from machine-readable payloads by default.
|
|
52
|
+
|
|
53
|
+
## Release gate checklist
|
|
54
|
+
|
|
55
|
+
- `npm run check`
|
|
56
|
+
- Node 20: `npx -y -p node@20 -c 'node -v && npm -v && npm run check'`
|
|
57
|
+
- `git diff --check`
|
|
58
|
+
- `npm audit --audit-level=moderate`
|
|
59
|
+
- `npm pack --dry-run --json`
|
|
60
|
+
- Secret scan changed source, docs, and config files before publishing or pushing.
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# First-Time Skill Control Flow
|
|
2
|
+
|
|
3
|
+
This flow assumes a user installed SkillBoard because they want to see and
|
|
4
|
+
control which agent skills can affect a workflow.
|
|
5
|
+
|
|
6
|
+
## 1. Bootstrap The Control Plane
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
skillboard init
|
|
10
|
+
skillboard doctor
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`init` creates the config, local `skills/` directory, report directories, and
|
|
14
|
+
agent bridge blocks. It also scans known local agent skill locations and records
|
|
15
|
+
discovered skills as managed entries. Trusted user-local skills, including
|
|
16
|
+
Hermes profile skills under `.hermes/profiles/*/skills`, are immediately
|
|
17
|
+
attached to a generated manual workflow as `status: active` with
|
|
18
|
+
`invocation: manual-only` when the project has no workflows yet, so existing
|
|
19
|
+
manual skills keep working through `can-use` and guard checks without creating
|
|
20
|
+
legacy-state warning noise. Runtime-supplied or external skills are quarantined
|
|
21
|
+
until an explicit source and workflow decision exists. Reviewable items should
|
|
22
|
+
appear as "Needs your decision"; only provenance failures, explicit user blocks,
|
|
23
|
+
disabled sources, or other hard policy failures should remain "Blocked for
|
|
24
|
+
safety". Use
|
|
25
|
+
`skillboard doctor --strict` when review-needed safe-mode warnings should fail
|
|
26
|
+
automation.
|
|
27
|
+
|
|
28
|
+
When the user asks the agent what it can use, the agent should run
|
|
29
|
+
`skillboard brief --json` first and answer from the brief rather than reading
|
|
30
|
+
skill files directly. The user-facing text output uses sections such as "What
|
|
31
|
+
your AI can use now", "Needs your decision", and "Blocked for safety"; text
|
|
32
|
+
briefs include previewable action cards by default, while the JSON form keeps
|
|
33
|
+
action cards opt-in. For large skill sets, the default text brief stays compact:
|
|
34
|
+
counts, top categories, next safe action, short previews per section, and short
|
|
35
|
+
action summaries. Use `skillboard brief --verbose` when you need every skill and
|
|
36
|
+
full copyable command details. Those action cards are suggestions only: the
|
|
37
|
+
agent should pick one current action id from the brief, request confirmation
|
|
38
|
+
before applying risk-bearing changes, then run
|
|
39
|
+
`skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json`
|
|
40
|
+
with `--workflow <name>` when a workflow is selected. The agent should read the
|
|
41
|
+
returned post-apply brief before making the next availability claim.
|
|
42
|
+
`apply-action` re-resolves the current brief and refuses stale action ids instead
|
|
43
|
+
of replaying cached action-card shell text.
|
|
44
|
+
|
|
45
|
+
Run this again after installing agent packages, plugins, workflow bundles, or
|
|
46
|
+
harnesses:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
skillboard inventory refresh --dry-run
|
|
50
|
+
skillboard inventory refresh
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## 2. Add A User-Owned Skill
|
|
54
|
+
|
|
55
|
+
Create the skill under the project `skills/` directory:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
mkdir -p skills/user-helper
|
|
59
|
+
$EDITOR skills/user-helper/SKILL.md
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Register it without making it callable yet:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
skillboard add skill user.helper \
|
|
66
|
+
--path user-helper \
|
|
67
|
+
--config skillboard.config.yaml \
|
|
68
|
+
--skills skills \
|
|
69
|
+
--dry-run
|
|
70
|
+
|
|
71
|
+
skillboard add skill user.helper \
|
|
72
|
+
--path user-helper \
|
|
73
|
+
--config skillboard.config.yaml \
|
|
74
|
+
--skills skills
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The dry run reports semantic YAML changes and leaves the config untouched. The
|
|
78
|
+
real command adds the skill as a direct user-owned `candidate` by default.
|
|
79
|
+
|
|
80
|
+
Create a workflow or harness for the skill without hand-editing YAML:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
skillboard add harness codex \
|
|
84
|
+
--config skillboard.config.yaml \
|
|
85
|
+
--skills skills
|
|
86
|
+
|
|
87
|
+
skillboard add workflow daily-workflow \
|
|
88
|
+
--harness codex \
|
|
89
|
+
--skill user.helper \
|
|
90
|
+
--config skillboard.config.yaml \
|
|
91
|
+
--skills skills
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
When `add workflow` attaches a `candidate` / `manual-only` skill, it promotes the
|
|
95
|
+
skill to `active` with `invocation: manual-only` for that workflow. It still
|
|
96
|
+
does not grant automatic model invocation.
|
|
97
|
+
|
|
98
|
+
## 3. Inspect Influence Before Use
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
skillboard explain user.helper \
|
|
102
|
+
--config skillboard.config.yaml \
|
|
103
|
+
--skills skills
|
|
104
|
+
|
|
105
|
+
skillboard can-use user.helper \
|
|
106
|
+
--workflow daily-workflow \
|
|
107
|
+
--config skillboard.config.yaml \
|
|
108
|
+
--skills skills
|
|
109
|
+
|
|
110
|
+
skillboard impact disable user.helper \
|
|
111
|
+
--config skillboard.config.yaml \
|
|
112
|
+
--skills skills \
|
|
113
|
+
--out .skillboard/reports/user-helper-impact.md
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`explain` shows source class, trust, owner install unit, workflow roles, and
|
|
117
|
+
capability roles. `can-use` is the machine-readable gate for agents. `impact`
|
|
118
|
+
shows which workflows and required outputs would be affected before disabling or
|
|
119
|
+
removing a skill.
|
|
120
|
+
|
|
121
|
+
For an actual invocation, `brief` is not the final permission check. Agents
|
|
122
|
+
should run `skillboard guard use ...` immediately before calling a skill so
|
|
123
|
+
state changes made after the brief cannot slip through.
|
|
124
|
+
|
|
125
|
+
When wiring a guard hook from an action card, keep `apply-action` as the
|
|
126
|
+
action-card primary flow:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
skillboard apply-action <action-id> --workflow daily-workflow --config skillboard.config.yaml --skills skills --yes --json
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The raw hook commands are underlying manual operator detail for previewing and
|
|
133
|
+
materializing an executable guard hook outside the action-card approval loop:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
skillboard hook install --workflow daily-workflow --config skillboard.config.yaml --skills skills --out .skillboard/hooks/daily-workflow-guard.sh --dry-run --json
|
|
137
|
+
skillboard hook install --workflow daily-workflow --config skillboard.config.yaml --skills skills --out .skillboard/hooks/daily-workflow-guard.sh
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
For direct manual hook installation, inspect the JSON `planned.preview.shell`
|
|
141
|
+
before an operator materializes the matching non-dry-run hook command.
|
|
142
|
+
|
|
143
|
+
## 4. Enable, Disable, Or Prefer
|
|
144
|
+
|
|
145
|
+
Enable the skill only for the workflow that should see it:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
skillboard activate user.helper \
|
|
149
|
+
--workflow daily-workflow \
|
|
150
|
+
--config skillboard.config.yaml \
|
|
151
|
+
--skills skills
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
If you already used `skillboard add workflow ... --skill user.helper`, this
|
|
155
|
+
manual activation step is not needed for direct user invocation.
|
|
156
|
+
|
|
157
|
+
Block it from a workflow without deleting the declaration or file:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
skillboard block user.helper \
|
|
161
|
+
--workflow daily-workflow \
|
|
162
|
+
--config skillboard.config.yaml \
|
|
163
|
+
--skills skills
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Prefer it for a capability when the workflow should depend on a role rather than
|
|
167
|
+
a raw skill id:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
skillboard prefer user.helper \
|
|
171
|
+
--workflow daily-workflow \
|
|
172
|
+
--capability task-review \
|
|
173
|
+
--config skillboard.config.yaml \
|
|
174
|
+
--skills skills
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## 5. Remove Governance Without Deleting User Files
|
|
178
|
+
|
|
179
|
+
First try the safe remove:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
skillboard remove skill user.helper \
|
|
183
|
+
--config skillboard.config.yaml \
|
|
184
|
+
--skills skills
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
If workflows, capabilities, or install units still reference the skill, the
|
|
188
|
+
command refuses to remove it and prints the references. After reviewing the
|
|
189
|
+
impact, remove the config declaration and references:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
skillboard remove skill user.helper \
|
|
193
|
+
--config skillboard.config.yaml \
|
|
194
|
+
--skills skills \
|
|
195
|
+
--force \
|
|
196
|
+
--dry-run
|
|
197
|
+
|
|
198
|
+
skillboard remove skill user.helper \
|
|
199
|
+
--config skillboard.config.yaml \
|
|
200
|
+
--skills skills \
|
|
201
|
+
--force
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
This removes SkillBoard policy references only. It does not delete
|
|
205
|
+
`skills/user-helper/SKILL.md`.
|
|
206
|
+
|
|
207
|
+
## 6. Stop Using SkillBoard Safely
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
skillboard uninstall --dry-run
|
|
211
|
+
skillboard uninstall
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Uninstall removes generated bridge blocks and unchanged helper files. It
|
|
215
|
+
preserves `skillboard.config.yaml`, `skills/`, reports, and user-authored
|
|
216
|
+
content in bridge files.
|
|
217
|
+
|
|
218
|
+
For a fresh policy lifecycle during testing, use:
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
skillboard uninstall --reset-config --remove-reports --remove-hooks --dry-run
|
|
222
|
+
skillboard uninstall --reset-config --remove-reports --remove-hooks
|
|
223
|
+
skillboard init
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
`--reset-config` discards the current SkillBoard config even if it contains
|
|
227
|
+
imported skills or workflow edits. `--remove-reports` also discards generated
|
|
228
|
+
dashboard and impact reports. `--remove-hooks` discards the entire
|
|
229
|
+
`.skillboard/hooks/` directory contents when you explicitly want a full test or
|
|
230
|
+
test reset, so `.skillboard/` can disappear when no other SkillBoard state
|
|
231
|
+
remains. These reset flags do not delete local `skills/` files.
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# Versioning
|
|
2
|
+
|
|
3
|
+
SkillBoard has several versioned surfaces. They should not all move at the same
|
|
4
|
+
pace, and not every skill file belongs in central version control.
|
|
5
|
+
|
|
6
|
+
This document defines the public alpha policy for releases, config compatibility,
|
|
7
|
+
source profiles, and the generated lockfile.
|
|
8
|
+
|
|
9
|
+
## Status
|
|
10
|
+
|
|
11
|
+
Current package version: `0.1.0`
|
|
12
|
+
|
|
13
|
+
Current config schema version:
|
|
14
|
+
|
|
15
|
+
```yaml
|
|
16
|
+
version: 1
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The project is a public alpha. Breaking changes are allowed before `1.0.0`, but
|
|
20
|
+
they must be documented in release notes and should include a migration note when
|
|
21
|
+
they affect user config.
|
|
22
|
+
|
|
23
|
+
## Versioned Surfaces
|
|
24
|
+
|
|
25
|
+
SkillBoard versions these surfaces deliberately:
|
|
26
|
+
|
|
27
|
+
- CLI package version: the npm package and command behavior.
|
|
28
|
+
- Config schema version: the top-level `version` field in
|
|
29
|
+
`skillboard.config.yaml`.
|
|
30
|
+
- Source profile format: YAML files under `profiles/` and project-specific
|
|
31
|
+
`.skillboard/profiles/`.
|
|
32
|
+
- Workflow contracts: workflow names, required capabilities, active skill pools,
|
|
33
|
+
required outputs, and harness choices.
|
|
34
|
+
- Capability contracts: canonical skill, alternatives, and default policy for a
|
|
35
|
+
capability.
|
|
36
|
+
- Exported skill entries: shared or vendor skills governed by SkillBoard.
|
|
37
|
+
- Install-unit entries: plugin, marketplace, package, harness, MCP, hook, agent,
|
|
38
|
+
and LSP sources.
|
|
39
|
+
- Lockfile data: pinned source/cache digest, skill content digests, policy, and
|
|
40
|
+
compatible harnesses.
|
|
41
|
+
|
|
42
|
+
SkillBoard does not try to centrally version every prompt or helper skill. A
|
|
43
|
+
workflow-internal private skill can remain inside that workflow package until it
|
|
44
|
+
becomes shared, auto-invokable, vendor-provided, or cross-workflow.
|
|
45
|
+
|
|
46
|
+
## Release Versioning
|
|
47
|
+
|
|
48
|
+
The package follows SemVer with a stricter alpha convention:
|
|
49
|
+
|
|
50
|
+
- Patch: bug fixes, docs, new tests, safer validation, and non-breaking profile
|
|
51
|
+
additions.
|
|
52
|
+
- Minor: new commands, new config fields with safe defaults, new report sections,
|
|
53
|
+
new built-in source profiles, and new policy checks that are warnings first.
|
|
54
|
+
- Major: post-`1.0.0` breaking CLI, config, or policy behavior.
|
|
55
|
+
|
|
56
|
+
Before `1.0.0`, breaking changes may happen in minor releases, but the changelog
|
|
57
|
+
must call them out clearly.
|
|
58
|
+
|
|
59
|
+
Suggested tags:
|
|
60
|
+
|
|
61
|
+
- `v0.1.0-alpha`: first public GitHub alpha.
|
|
62
|
+
- `v0.2.0-alpha`: source inventory refresh, doctor/status, source pin refresh,
|
|
63
|
+
installer/config detection, resilient detector warnings, and richer dry-run
|
|
64
|
+
plans.
|
|
65
|
+
- `v0.3.0-alpha`: signed remote source verification hardening and migration
|
|
66
|
+
workflow.
|
|
67
|
+
- `v1.0.0`: config schema and core CLI behavior are stable enough for external
|
|
68
|
+
workflows to rely on.
|
|
69
|
+
|
|
70
|
+
## Config Schema Version
|
|
71
|
+
|
|
72
|
+
The top-level `version` field is the schema version, not the package version.
|
|
73
|
+
|
|
74
|
+
Rules:
|
|
75
|
+
|
|
76
|
+
- `version: 1` is the only supported schema today.
|
|
77
|
+
- Missing `version` is treated as `1` for early compatibility.
|
|
78
|
+
- Unsupported future versions must fail fast rather than silently parsing with
|
|
79
|
+
older semantics.
|
|
80
|
+
- New fields should default to the safest behavior.
|
|
81
|
+
- New automatic invocation behavior must be opt-in.
|
|
82
|
+
- New policy checks should start as warnings unless they protect an important
|
|
83
|
+
safety boundary.
|
|
84
|
+
|
|
85
|
+
Breaking schema changes need a migration note. A future `skillboard migrate`
|
|
86
|
+
command can automate those changes, but it is not implemented yet.
|
|
87
|
+
|
|
88
|
+
## Source Profile Versioning
|
|
89
|
+
|
|
90
|
+
Source profiles are data, not hardcoded adapter branches. Built-in profiles live
|
|
91
|
+
under `profiles/`; project profiles can live under `.skillboard/profiles/`.
|
|
92
|
+
|
|
93
|
+
Profile compatibility rules:
|
|
94
|
+
|
|
95
|
+
- Adding a new built-in profile is a patch or minor change.
|
|
96
|
+
- Changing a built-in profile's namespace, target path prefix, default status,
|
|
97
|
+
default invocation, or default exposure is a breaking profile behavior change.
|
|
98
|
+
- External profiles should not grant `global-auto` unless they also mark the
|
|
99
|
+
imported skills as `global-meta`.
|
|
100
|
+
- External repository skills should normally import as `vendor`, `candidate`, or
|
|
101
|
+
`quarantined`, with `manual-only` or `router-only` invocation.
|
|
102
|
+
- Harness/plugin bundle profiles should use `unit-managed` for child skills when
|
|
103
|
+
the parent bundle owns commands, hooks, MCP servers, or config mutation.
|
|
104
|
+
|
|
105
|
+
Profile imports can be reviewed as fragments or merged directly:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
skillboard import \
|
|
109
|
+
--profile github.mattpocock.skills \
|
|
110
|
+
--source-root /path/to/source \
|
|
111
|
+
--out .skillboard/reports/import-fragment.yaml
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
skillboard import \
|
|
116
|
+
--profile github.mattpocock.skills \
|
|
117
|
+
--source-root /path/to/source \
|
|
118
|
+
--config skillboard.config.yaml \
|
|
119
|
+
--merge \
|
|
120
|
+
--dry-run
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`--merge` is append-only by default. `--replace` is required to overwrite
|
|
124
|
+
existing skill or install-unit ids. Drop `--dry-run` only after reviewing the
|
|
125
|
+
reported text and YAML semantic change plan.
|
|
126
|
+
|
|
127
|
+
## Workflow And Capability Versioning
|
|
128
|
+
|
|
129
|
+
The primary unit of compatibility is the workflow, not an individual skill.
|
|
130
|
+
|
|
131
|
+
Version these centrally:
|
|
132
|
+
|
|
133
|
+
- workflow name and intent;
|
|
134
|
+
- harness and fallback harness assumptions;
|
|
135
|
+
- required capabilities;
|
|
136
|
+
- active, blocked, and manual-only skill pools;
|
|
137
|
+
- required outputs;
|
|
138
|
+
- exported skill contracts used by more than one workflow;
|
|
139
|
+
- policy decisions that allow automatic invocation.
|
|
140
|
+
|
|
141
|
+
Avoid central versioning for:
|
|
142
|
+
|
|
143
|
+
- one-off prompts;
|
|
144
|
+
- workflow-internal helper skills;
|
|
145
|
+
- private skills used by only one workflow;
|
|
146
|
+
- temporary templates that are not auto-invokable;
|
|
147
|
+
- implementation details inside a harness bundle.
|
|
148
|
+
|
|
149
|
+
When a workflow changes its required outputs, required capabilities, or
|
|
150
|
+
workflow-auto skill set, treat it as a compatibility change even if no file paths
|
|
151
|
+
changed.
|
|
152
|
+
|
|
153
|
+
## Lockfile Policy
|
|
154
|
+
|
|
155
|
+
`skillboard lock write` generates `skillboard.lock.yaml` from the current
|
|
156
|
+
workspace.
|
|
157
|
+
|
|
158
|
+
The lockfile pins:
|
|
159
|
+
|
|
160
|
+
- config schema version;
|
|
161
|
+
- install-unit source, cache path, verified path, digest, and trust status;
|
|
162
|
+
- skill id, path, and content hash;
|
|
163
|
+
- workflow/capability bindings;
|
|
164
|
+
- generated timestamp.
|
|
165
|
+
|
|
166
|
+
The lockfile should represent a verified working set, not a desired-state file.
|
|
167
|
+
Users should edit `skillboard.config.yaml`; tools should generate the lockfile.
|
|
168
|
+
Local `source` and `cache_path` entries are digest-verified by `skillboard audit
|
|
169
|
+
sources --verify`. Remote or command-based sources need a configured
|
|
170
|
+
`source_digest` and, when signatures are used, a matching `public_key`.
|
|
171
|
+
Fetchable Git sources can be materialized and pinned with `skillboard sources
|
|
172
|
+
refresh`, which updates `cache_path`, `source_digest`, and `verified_at` in the
|
|
173
|
+
config after cloning into `.skillboard/sources/`.
|
|
174
|
+
Relative local paths are resolved from the config directory first and then from
|
|
175
|
+
the current working directory, so bundled examples can use project-root-relative
|
|
176
|
+
paths while project configs can still keep config-local paths.
|
|
177
|
+
`skillboard lock write` refuses to write when verification has errors unless
|
|
178
|
+
`--allow-unverified` is passed explicitly for investigation artifacts.
|
|
179
|
+
|
|
180
|
+
## Release Checklist
|
|
181
|
+
|
|
182
|
+
Before tagging a public release:
|
|
183
|
+
|
|
184
|
+
- Run `npm run check`.
|
|
185
|
+
- Run `node --check` across `src`, `test`, and `bin`.
|
|
186
|
+
- Run `npm pack --dry-run --json` and confirm internal artifacts are excluded.
|
|
187
|
+
- Run at least one CLI smoke test through the public surface.
|
|
188
|
+
- Confirm docs mention any breaking config, profile, or CLI changes.
|
|
189
|
+
- Update package version and release notes.
|
|
190
|
+
|
|
191
|
+
For alpha releases, include a short "completion notes" section. Current
|
|
192
|
+
completion notes:
|
|
193
|
+
|
|
194
|
+
- source inventory refresh covers known local agent skill roots, plugin-cache
|
|
195
|
+
manifests, and user-supplied scan roots;
|
|
196
|
+
- `sources refresh` covers Git-compatible remote sources and digest pin refresh;
|
|
197
|
+
- `inventory detect` covers installer output and explicit mutated config files
|
|
198
|
+
for commands, hooks, MCP servers, and modified config paths;
|
|
199
|
+
- dry-run plans report a capped YAML semantic change list rather than full patch
|
|
200
|
+
hunks;
|
|
201
|
+
- unusual YAML trivia may still be normalized during structured config writes.
|