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.
Files changed (94) hide show
  1. package/CONTRIBUTING.md +83 -0
  2. package/LICENSE +21 -0
  3. package/README.md +645 -0
  4. package/bin/skillboard.mjs +4 -0
  5. package/docs/adapters.md +127 -0
  6. package/docs/capabilities.md +107 -0
  7. package/docs/install.md +346 -0
  8. package/docs/plans/20260625-080025-skillboard-mvp-review.md +189 -0
  9. package/docs/plans/README.md +20 -0
  10. package/docs/policy-model.md +251 -0
  11. package/docs/positioning.md +94 -0
  12. package/docs/profiles.md +166 -0
  13. package/docs/rollout-runbook.md +60 -0
  14. package/docs/user-flow.md +231 -0
  15. package/docs/versioning.md +201 -0
  16. package/examples/multi-source-skills/anthropic/docx/SKILL.md +8 -0
  17. package/examples/multi-source-skills/anthropic/skill-creator/SKILL.md +8 -0
  18. package/examples/multi-source-skills/matt/grill-me/SKILL.md +8 -0
  19. package/examples/multi-source-skills/matt/tdd/SKILL.md +8 -0
  20. package/examples/multi-source-skills/omo/review-work/SKILL.md +8 -0
  21. package/examples/multi-source-skills/omo/ulw-plan/SKILL.md +8 -0
  22. package/examples/multi-source-skills/private/tdd-work-continuity/SKILL.md +8 -0
  23. package/examples/multi-source-skills/private/workflow-router/SKILL.md +8 -0
  24. package/examples/multi-source-skills/wshobson/python-testing/SKILL.md +8 -0
  25. package/examples/multi-source-skills/wshobson/security-review/SKILL.md +8 -0
  26. package/examples/multi-source.config.yaml +271 -0
  27. package/examples/skillboard.config.yaml +194 -0
  28. package/examples/skills/grill-me/SKILL.md +9 -0
  29. package/examples/skills/grill-with-docs/SKILL.md +9 -0
  30. package/examples/skills/requirement-intake/SKILL.md +9 -0
  31. package/examples/skills/tdd/SKILL.md +8 -0
  32. package/package.json +58 -0
  33. package/profiles/anthropics-skills.yaml +17 -0
  34. package/profiles/mattpocock-skills.yaml +26 -0
  35. package/profiles/oh-my-openagent.yaml +32 -0
  36. package/profiles/voltagent-awesome-agent-skills.yaml +18 -0
  37. package/profiles/wshobson-agents.yaml +19 -0
  38. package/src/advisor/action-core.mjs +74 -0
  39. package/src/advisor/actions.mjs +256 -0
  40. package/src/advisor/application-commands.mjs +59 -0
  41. package/src/advisor/apply-action.mjs +183 -0
  42. package/src/advisor/schema.mjs +112 -0
  43. package/src/advisor/setup-actions.mjs +42 -0
  44. package/src/advisor/skills.mjs +191 -0
  45. package/src/advisor/sort.mjs +15 -0
  46. package/src/advisor/sources.mjs +160 -0
  47. package/src/advisor/trust-policy.mjs +65 -0
  48. package/src/advisor/workflow.mjs +41 -0
  49. package/src/advisor.mjs +134 -0
  50. package/src/agent-inventory-platforms.mjs +100 -0
  51. package/src/agent-inventory.mjs +804 -0
  52. package/src/brief-cli.mjs +40 -0
  53. package/src/brief-renderer.mjs +362 -0
  54. package/src/change-plan.mjs +169 -0
  55. package/src/cli.mjs +1171 -0
  56. package/src/config-helpers.mjs +72 -0
  57. package/src/control/can-use-guard.mjs +91 -0
  58. package/src/control/config-write.mjs +163 -0
  59. package/src/control/skill-crud.mjs +394 -0
  60. package/src/control/source-trust.mjs +161 -0
  61. package/src/control/workflow-crud.mjs +104 -0
  62. package/src/control.mjs +197 -0
  63. package/src/doctor.mjs +299 -0
  64. package/src/domain/constants.mjs +47 -0
  65. package/src/domain/indexes.mjs +29 -0
  66. package/src/domain/rules/capabilities.mjs +33 -0
  67. package/src/domain/rules/harnesses.mjs +16 -0
  68. package/src/domain/rules/install-units.mjs +95 -0
  69. package/src/domain/rules/skills.mjs +105 -0
  70. package/src/domain/rules/workflows.mjs +105 -0
  71. package/src/domain/skill-state-matrix.mjs +79 -0
  72. package/src/domain/source-classes.mjs +99 -0
  73. package/src/hook-plan.mjs +152 -0
  74. package/src/impact.mjs +41 -0
  75. package/src/index.mjs +82 -0
  76. package/src/init.mjs +136 -0
  77. package/src/install-output-detector.mjs +337 -0
  78. package/src/install-units.mjs +62 -0
  79. package/src/inventory-refresh.mjs +45 -0
  80. package/src/lifecycle-cli.mjs +166 -0
  81. package/src/lifecycle-content.mjs +87 -0
  82. package/src/policy.mjs +42 -0
  83. package/src/reconcile.mjs +111 -0
  84. package/src/report.mjs +151 -0
  85. package/src/review.mjs +88 -0
  86. package/src/rollout.mjs +453 -0
  87. package/src/skill-paths.mjs +17 -0
  88. package/src/source-cache.mjs +178 -0
  89. package/src/source-profile-loader.mjs +160 -0
  90. package/src/source-profiles.mjs +299 -0
  91. package/src/source-verification.mjs +252 -0
  92. package/src/uninstall.mjs +258 -0
  93. package/src/workspace.mjs +219 -0
  94. package/tsconfig.lsp.json +15 -0
@@ -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.
@@ -0,0 +1,8 @@
1
+ ---
2
+ name: anthropic.docx
3
+ description: Create and edit Word documents.
4
+ ---
5
+
6
+ # Anthropic DOCX
7
+
8
+ Document workflow skill.
@@ -0,0 +1,8 @@
1
+ ---
2
+ name: anthropic.skill-creator
3
+ description: Create Agent Skills with the standard skill structure.
4
+ ---
5
+
6
+ # Anthropic Skill Creator
7
+
8
+ Reference skill authoring workflow.
@@ -0,0 +1,8 @@
1
+ ---
2
+ name: matt.grill-me
3
+ description: Clarify vague requirements before implementation.
4
+ ---
5
+
6
+ # Matt Grill Me
7
+
8
+ Vendor requirement clarification skill.
@@ -0,0 +1,8 @@
1
+ ---
2
+ name: matt.tdd
3
+ description: Run test-driven implementation loops.
4
+ ---
5
+
6
+ # Matt TDD
7
+
8
+ Vendor TDD workflow skill.