agent-skillboard 0.1.2 → 0.2.2

package/docs/versioning.md

@@ -1,117 +1,119 @@
-# Versioning
-
-SkillBoard has several versioned surfaces. They should not all move at the same
-pace, and not every skill file belongs in central version control.
-
+# Versioning
+
+SkillBoard has several versioned surfaces. They should not all move at the same
+pace, and not every skill file belongs in central version control.
+
 This document defines the public alpha policy for releases, config compatibility,
 source profiles, and the generated lockfile.
-
-## Status
-
-Current package version: `0.1.2`
-
-Current config schema version:
-
-```yaml
-version: 1
-```
-
-The project is a public alpha. Breaking changes are allowed before `1.0.0`, but
-they must be documented in release notes and should include a migration note when
-they affect user config.
-
-## Versioned Surfaces
-
-SkillBoard versions these surfaces deliberately:
-
-- CLI package version: the npm package and command behavior.
-- Config schema version: the top-level `version` field in
-  `skillboard.config.yaml`.
-- Source profile format: YAML files under `profiles/` and project-specific
-  `.skillboard/profiles/`.
-- Workflow contracts: workflow names, required capabilities, active skill pools,
-  required outputs, and harness choices.
-- Capability contracts: canonical skill, alternatives, and default policy for a
-  capability.
-- Exported skill entries: shared or vendor skills governed by SkillBoard.
-- Install-unit entries: plugin, marketplace, package, harness, MCP, hook, agent,
-  and LSP sources.
+
+## Status
+
+Current package version: `0.2.2`
+
+Current config schema version:
+
+```yaml
+version: 1
+```
+
+The project is a public alpha. Breaking changes are allowed before `1.0.0`, but
+they must be documented in release notes and should include a migration note when
+they affect user config.
+
+## Versioned Surfaces
+
+SkillBoard versions these surfaces deliberately:
+
+- CLI package version: the npm package and command behavior.
+- Config schema version: the top-level `version` field in
+  `skillboard.config.yaml`.
+- Source profile format: YAML files under `profiles/` and project-specific
+  `.skillboard/profiles/`.
+- Workflow contracts: workflow names, required capabilities, active skill pools,
+  required outputs, and harness choices.
+- Capability contracts: canonical skill, alternatives, and default policy for a
+  capability.
+- Exported skill entries: shared or vendor skills governed by SkillBoard.
+- Install-unit entries: plugin, marketplace, package, harness, MCP, hook, agent,
+  and LSP sources.
 - Lockfile data: pinned source/cache digest, skill content digests, policy, and
   compatible harnesses.
-
-SkillBoard does not try to centrally version every prompt or helper skill. A
-workflow-internal private skill can remain inside that workflow package until it
-becomes shared, auto-invokable, vendor-provided, or cross-workflow.
-
-## Release Versioning
-
-The package follows SemVer with a stricter alpha convention:
-
-- Patch: bug fixes, docs, new tests, safer validation, and non-breaking profile
-  additions.
-- Minor: new commands, new config fields with safe defaults, new report sections,
-  new built-in source profiles, and new policy checks that are warnings first.
-- Major: post-`1.0.0` breaking CLI, config, or policy behavior.
-
-Before `1.0.0`, breaking changes may happen in minor releases, but the changelog
-must call them out clearly.
-
+
+SkillBoard does not try to centrally version every prompt or helper skill. A
+workflow-internal private skill can remain inside that workflow package until it
+becomes shared, auto-invokable, vendor-provided, or cross-workflow.
+
+## Release Versioning
+
+The package follows SemVer with a stricter alpha convention:
+
+- Patch: bug fixes, docs, new tests, safer validation, and non-breaking profile
+  additions.
+- Minor: new commands, new config fields with safe defaults, new report sections,
+  new built-in source profiles, and new policy checks that are warnings first.
+- Major: post-`1.0.0` breaking CLI, config, or policy behavior.
+
+Before `1.0.0`, breaking changes may happen in minor releases, but the changelog
+must call them out clearly.
+
 Suggested tags:
 
 - `v0.1.0-alpha`: first public GitHub alpha.
-- `v0.2.0-alpha`: source inventory refresh, doctor/status, source pin refresh,
+- `v0.2.2`: one-time runtime source review before manual activation, ask-after
+  skill routing, README benefit-first positioning,
+  source inventory refresh, doctor/status, source pin refresh,
   installer/config detection, resilient detector warnings, and richer dry-run
   plans.
 - `v0.3.0-alpha`: signed remote source verification hardening and migration
   workflow.
 - `v1.0.0`: config schema and core CLI behavior are stable enough for external
   workflows to rely on.
-
-## Config Schema Version
-
-The top-level `version` field is the schema version, not the package version.
-
-Rules:
-
-- `version: 1` is the only supported schema today.
-- Missing `version` is treated as `1` for early compatibility.
-- Unsupported future versions must fail fast rather than silently parsing with
-  older semantics.
-- New fields should default to the safest behavior.
-- New automatic invocation behavior must be opt-in.
-- New policy checks should start as warnings unless they protect an important
-  safety boundary.
-
-Breaking schema changes need a migration note. A future `skillboard migrate`
-command can automate those changes, but it is not implemented yet.
-
-## Source Profile Versioning
-
-Source profiles are data, not hardcoded adapter branches. Built-in profiles live
-under `profiles/`; project profiles can live under `.skillboard/profiles/`.
-
-Profile compatibility rules:
-
-- Adding a new built-in profile is a patch or minor change.
-- Changing a built-in profile's namespace, target path prefix, default status,
-  default invocation, or default exposure is a breaking profile behavior change.
-- External profiles should not grant `global-auto` unless they also mark the
-  imported skills as `global-meta`.
-- External repository skills should normally import as `vendor`, `candidate`, or
-  `quarantined`, with `manual-only` or `router-only` invocation.
-- Harness/plugin bundle profiles should use `unit-managed` for child skills when
-  the parent bundle owns commands, hooks, MCP servers, or config mutation.
-
-Profile imports can be reviewed as fragments or merged directly:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --out .skillboard/reports/import-fragment.yaml
-```
-
-```bash
+
+## Config Schema Version
+
+The top-level `version` field is the schema version, not the package version.
+
+Rules:
+
+- `version: 1` is the only supported schema today.
+- Missing `version` is treated as `1` for early compatibility.
+- Unsupported future versions must fail fast rather than silently parsing with
+  older semantics.
+- New fields should default to the safest behavior.
+- New automatic invocation behavior must be opt-in.
+- New policy checks should start as warnings unless they protect an important
+  safety boundary.
+
+Breaking schema changes need a migration note. A future `skillboard migrate`
+command can automate those changes, but it is not implemented yet.
+
+## Source Profile Versioning
+
+Source profiles are data, not hardcoded adapter branches. Built-in profiles live
+under `profiles/`; project profiles can live under `.skillboard/profiles/`.
+
+Profile compatibility rules:
+
+- Adding a new built-in profile is a patch or minor change.
+- Changing a built-in profile's namespace, target path prefix, default status,
+  default invocation, or default exposure is a breaking profile behavior change.
+- External profiles should not grant `global-auto` unless they also mark the
+  imported skills as `global-meta`.
+- External repository skills should normally import as `vendor`, `candidate`, or
+  `quarantined`, with `manual-only` or `router-only` invocation.
+- Harness/plugin bundle profiles should use `unit-managed` for child skills when
+  the parent bundle owns commands, hooks, MCP servers, or config mutation.
+
+Profile imports can be reviewed as fragments or merged directly:
+
+```bash
+skillboard import \
+  --profile github.mattpocock.skills \
+  --source-root /path/to/source \
+  --out .skillboard/reports/import-fragment.yaml
+```
+
+```bash
 skillboard import \
   --profile github.mattpocock.skills \
   --source-root /path/to/source \
@@ -123,33 +125,33 @@ skillboard import \
 `--merge` is append-only by default. `--replace` is required to overwrite
 existing skill or install-unit ids. Drop `--dry-run` only after reviewing the
 reported text and YAML semantic change plan.
-
-## Workflow And Capability Versioning
-
-The primary unit of compatibility is the workflow, not an individual skill.
-
-Version these centrally:
-
-- workflow name and intent;
-- harness and fallback harness assumptions;
-- required capabilities;
-- active, blocked, and manual-only skill pools;
-- required outputs;
-- exported skill contracts used by more than one workflow;
-- policy decisions that allow automatic invocation.
-
-Avoid central versioning for:
-
-- one-off prompts;
-- workflow-internal helper skills;
-- private skills used by only one workflow;
-- temporary templates that are not auto-invokable;
-- implementation details inside a harness bundle.
-
-When a workflow changes its required outputs, required capabilities, or
-workflow-auto skill set, treat it as a compatibility change even if no file paths
-changed.
-
+
+## Workflow And Capability Versioning
+
+The primary unit of compatibility is the workflow, not an individual skill.
+
+Version these centrally:
+
+- workflow name and intent;
+- harness and fallback harness assumptions;
+- required capabilities;
+- active, blocked, and manual-only skill pools;
+- required outputs;
+- exported skill contracts used by more than one workflow;
+- policy decisions that allow automatic invocation.
+
+Avoid central versioning for:
+
+- one-off prompts;
+- workflow-internal helper skills;
+- private skills used by only one workflow;
+- temporary templates that are not auto-invokable;
+- implementation details inside a harness bundle.
+
+When a workflow changes its required outputs, required capabilities, or
+workflow-auto skill set, treat it as a compatibility change even if no file paths
+changed.
+
 ## Lockfile Policy
 
 `skillboard lock write` generates `skillboard.lock.yaml` from the current
@@ -176,7 +178,7 @@ the current working directory, so bundled examples can use project-root-relative
 paths while project configs can still keep config-local paths.
 `skillboard lock write` refuses to write when verification has errors unless
 `--allow-unverified` is passed explicitly for investigation artifacts.
-
+
 ## Release Checklist
 
 Before tagging a public release:
@@ -187,15 +189,13 @@ Before tagging a public release:
 - Run at least one CLI smoke test through the public surface.
 - Confirm docs mention any breaking config, profile, or CLI changes.
 - Update package version and release notes.
-- Confirm npm Trusted Publisher is configured for package `agent-skillboard`,
-  repository `NyXXiR/skillboard`, workflow filename `publish.yml`, and allowed
-  action `npm publish`.
-  - If `npm trust github agent-skillboard --repo NyXXiR/skillboard --file
-    publish.yml --allow-publish` cannot configure it from the CLI, use the npm
-    package settings page and add a GitHub Actions trusted publisher with the
-    same repository, workflow filename, and allowed action.
-- Push a version tag that exactly matches `package.json`, for example `v0.1.2`
-  for package version `0.1.2`.
+- Confirm the repository `NPM_TOKEN` secret can publish `agent-skillboard`.
+  The publish job uses that token for npm authentication and requests
+  provenance with GitHub Actions OIDC, so keep `permissions.id-token: write`,
+  the npm registry URL in `setup-node`, and
+  `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` on the publish step.
+- Push a version tag that exactly matches `package.json`, for example `v0.2.2`
+  for package version `0.2.2`.
 - Let `.github/workflows/publish.yml` publish from the tag. The workflow runs
   the full check suite, validates that the tag matches the package version, and
   skips `npm publish` only when that exact version already exists on npm.
@@ -228,3 +228,19 @@ completion notes:
 - add a dedicated test for the version flags;
 - update README quick-start to verify the installed version before running
   policy commands.
+
+## 0.2.2 Completion Notes
+
+- recommend one-time review, not default blocking, for high-risk runtime/plugin
+  install units;
+- after source review, allow quarantined runtime/plugin skills to be activated
+  as `manual-only` workflow skills before any ask-after preference is recorded;
+- add ask-after route policy suggestions for safe ambiguous workflow skill
+  matches while preserving the public route JSON contract;
+- carry route candidate guard and capability roles into AI-facing brief
+  guidance;
+- keep no-match and guard-denied routes free of use disclosures or post-use
+  policy suggestions;
+- update README positioning around user benefit, no-global-install usage,
+  read-only normal checks, explicit approval for policy changes, and
+  conservative previewable cleanup.

package/examples/multi-source-skills/anthropic/docx/SKILL.md

@@ -1,8 +1,8 @@
----
-name: anthropic.docx
-description: Create and edit Word documents.
----
-
-# Anthropic DOCX
-
-Document workflow skill.
+---
+name: anthropic.docx
+description: Create and edit Word documents.
+---
+
+# Anthropic DOCX
+
+Document workflow skill.

package/examples/multi-source-skills/anthropic/skill-creator/SKILL.md

@@ -1,8 +1,8 @@
----
-name: anthropic.skill-creator
-description: Create Agent Skills with the standard skill structure.
----
-
-# Anthropic Skill Creator
-
-Reference skill authoring workflow.
+---
+name: anthropic.skill-creator
+description: Create Agent Skills with the standard skill structure.
+---
+
+# Anthropic Skill Creator
+
+Reference skill authoring workflow.

package/examples/multi-source-skills/matt/grill-me/SKILL.md

@@ -1,8 +1,8 @@
----
-name: matt.grill-me
-description: Clarify vague requirements before implementation.
----
-
-# Matt Grill Me
-
-Vendor requirement clarification skill.
+---
+name: matt.grill-me
+description: Clarify vague requirements before implementation.
+---
+
+# Matt Grill Me
+
+Vendor requirement clarification skill.

package/examples/multi-source-skills/matt/tdd/SKILL.md

@@ -1,8 +1,8 @@
----
-name: matt.tdd
-description: Run test-driven implementation loops.
----
-
-# Matt TDD
-
-Vendor TDD workflow skill.
+---
+name: matt.tdd
+description: Run test-driven implementation loops.
+---
+
+# Matt TDD
+
+Vendor TDD workflow skill.

package/examples/multi-source-skills/omo/review-work/SKILL.md

@@ -1,8 +1,8 @@
----
-name: omo.review-work
-description: Review completed implementation work with strict verification.
----
-
-# OMO Review Work
-
-Harness-owned post-implementation review skill.
+---
+name: omo.review-work
+description: Review completed implementation work with strict verification.
+---
+
+# OMO Review Work
+
+Harness-owned post-implementation review skill.

package/examples/multi-source-skills/omo/ulw-plan/SKILL.md

@@ -1,8 +1,8 @@
----
-name: omo.ulw-plan
-description: Plan complex work in a LazyCodex harness.
----
-
-# OMO ULW Plan
-
-Harness-owned planning skill.
+---
+name: omo.ulw-plan
+description: Plan complex work in a LazyCodex harness.
+---
+
+# OMO ULW Plan
+
+Harness-owned planning skill.

package/examples/multi-source-skills/private/tdd-work-continuity/SKILL.md

@@ -1,8 +1,8 @@
----
-name: private.tdd-work-continuity
-description: Keep local TDD work resumable with plan and verification notes.
----
-
-# Private TDD Work Continuity
-
-Maintain continuity for project-specific engineering workflows.
+---
+name: private.tdd-work-continuity
+description: Keep local TDD work resumable with plan and verification notes.
+---
+
+# Private TDD Work Continuity
+
+Maintain continuity for project-specific engineering workflows.

package/examples/multi-source-skills/private/workflow-router/SKILL.md

@@ -1,8 +1,8 @@
----
-name: private.workflow-router
-description: Route incoming work to the correct workflow before exposing specialized skills.
----
-
-# Private Workflow Router
-
-Keep global routing small and explicit.
+---
+name: private.workflow-router
+description: Route incoming work to the correct workflow before exposing specialized skills.
+---
+
+# Private Workflow Router
+
+Keep global routing small and explicit.

package/examples/multi-source-skills/wshobson/python-testing/SKILL.md

@@ -1,8 +1,8 @@
----
-name: wshobson.python-testing
-description: Python testing workflow skill.
----
-
-# Wshobson Python Testing
-
-Marketplace skill for Python test workflows.
+---
+name: wshobson.python-testing
+description: Python testing workflow skill.
+---
+
+# Wshobson Python Testing
+
+Marketplace skill for Python test workflows.

package/examples/multi-source-skills/wshobson/security-review/SKILL.md

@@ -1,8 +1,8 @@
----
-name: wshobson.security-review
-description: Security review workflow skill.
----
-
-# Wshobson Security Review
-
-Marketplace skill for security review workflows.
+---
+name: wshobson.security-review
+description: Security review workflow skill.
+---
+
+# Wshobson Security Review
+
+Marketplace skill for security review workflows.

package/examples/skillboard.config.yaml

@@ -1,6 +1,11 @@
-version: 1
-
-defaults:
+# Intentional policy-failure fixture.
+# This file is used by the value-proof tests to show why a raw skill list can
+# look usable while SkillBoard correctly reports policy errors. Use
+# examples/multi-source.config.yaml for a passing multi-source example.
+
+version: 1
+
+defaults:
   invocation_policy: deny-by-default
   allow_model_invocation: false
   require_explicit_workflow: true

package/examples/skills/grill-me/SKILL.md

@@ -1,9 +1,9 @@
----
-name: grill-me
-description: Ask strict clarifying questions before work begins.
----
-
-# Grill Me
-
-Vendor skill kept for manual comparison. It is blocked in the sample night
-workflow because `requirement-intake` is canonical.
+---
+name: grill-me
+description: Ask strict clarifying questions before work begins.
+---
+
+# Grill Me
+
+Vendor skill kept for manual comparison. It is blocked in the sample night
+workflow because `requirement-intake` is canonical.

package/examples/skills/grill-with-docs/SKILL.md

@@ -1,9 +1,9 @@
----
-name: matt.grill-with-docs
-description: Requirement clarification that also updates durable project docs.
----
-
-# Grill With Docs
-
-Use only when a workflow explicitly allows requirements clarification that
-changes durable project documentation.
+---
+name: matt.grill-with-docs
+description: Requirement clarification that also updates durable project docs.
+---
+
+# Grill With Docs
+
+Use only when a workflow explicitly allows requirements clarification that
+changes durable project documentation.

package/examples/skills/requirement-intake/SKILL.md

@@ -1,9 +1,9 @@
----
-name: requirement-intake
-description: Route vague feature requests into clear requirements, open questions, and implementation-ready scope.
----
-
-# Requirement Intake
-
-Use when a task needs clarification before implementation. Produce a short
-decision brief, unresolved owner decisions, and a suggested workflow.
+---
+name: requirement-intake
+description: Route vague feature requests into clear requirements, open questions, and implementation-ready scope.
+---
+
+# Requirement Intake
+
+Use when a task needs clarification before implementation. Produce a short
+decision brief, unresolved owner decisions, and a suggested workflow.

package/examples/skills/tdd/SKILL.md

@@ -1,8 +1,8 @@
----
-name: tdd
-description: Drive coding tasks through failing-first tests, implementation, and verification.
----
-
-# TDD
-
-Use when implementation work needs a red-green verification loop.
+---
+name: tdd
+description: Drive coding tasks through failing-first tests, implementation, and verification.
+---
+
+# TDD
+
+Use when implementation work needs a red-green verification loop.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "agent-skillboard",
-  "version": "0.1.2",
-  "description": "Policy and visibility layer for AI agent skills.",
+  "version": "0.2.2",
+  "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",
+    "agent-skills",
     "skills",
+    "skill-routing",
+    "workflow",
     "codex",
     "claude-code",
     "policy"
@@ -21,7 +24,7 @@
   "files": [
     "bin",
     "src",
-    "docs",
+    "docs/*.md",
     "examples",
     "profiles",
     "README.md",