agent-skillboard 0.1.2 → 0.2.1

package/docs/adapters.md

@@ -1,34 +1,34 @@
-# Adapter Model
-
-SkillBoard should not hardcode one adapter per popular repository.
-
-The core should stay generic, and repository-specific behavior should live in
-data-driven source profiles wherever possible.
-
-## Layers
-
-1. Core scanners
-
-   Generic code that understands common primitives:
-
-   - `SKILL.md` folders with YAML frontmatter;
-   - plugin or marketplace manifests;
-   - package manager metadata;
-   - known user/project install scopes;
-   - command, hook, MCP, agent, and LSP component lists.
-
-2. Source profiles
-
-   Declarative profiles that describe how to interpret a source:
-
-   ```yaml
-   id: github.mattpocock.skills
-   source: mattpocock/skills
-   kind: marketplace
-   namespace: matt
-   target_path_prefix: matt
-   default_status: vendor
-   default_invocation: manual-only
+# Adapter Model
+
+SkillBoard should not hardcode one adapter per popular repository.
+
+The core should stay generic, and repository-specific behavior should live in
+data-driven source profiles wherever possible.
+
+## Layers
+
+1. Core scanners
+
+   Generic code that understands common primitives:
+
+   - `SKILL.md` folders with YAML frontmatter;
+   - plugin or marketplace manifests;
+   - package manager metadata;
+   - known user/project install scopes;
+   - command, hook, MCP, agent, and LSP component lists.
+
+2. Source profiles
+
+   Declarative profiles that describe how to interpret a source:
+
+   ```yaml
+   id: github.mattpocock.skills
+   source: mattpocock/skills
+   kind: marketplace
+   namespace: matt
+   target_path_prefix: matt
+   default_status: vendor
+   default_invocation: manual-only
    default_exposure: exported
    skill_paths:
      - "skills/**/SKILL.md"
@@ -49,62 +49,62 @@ data-driven source profiles wherever possible.
    `SKILL.md` path. For example, `skills/engineering/tdd/SKILL.md` with segment
    `1` becomes category `engineering`. `path_rules` apply first-match overrides
    for repository conventions such as `deprecated` or `in-progress` folders.
-
-3. Detector plugins
-
-   Code adapters are only for sources whose layout cannot be described
-   declaratively, such as installers that mutate multiple config files or require
-   command output parsing. These should be small detector modules that produce the
-   same install-unit data model as profiles.
-
-## Built-In Profiles Are Not Hardcoding
-
-SkillBoard can ship built-in profiles for popular ecosystems, but they should be
-treated as bundled data, not product logic. Users and communities should be able
-to add or override profiles without forking the CLI.
-
-Good built-ins:
-
-- `mattpocock/skills`: skill pack profile.
-- `code-yeongyu/oh-my-openagent`: harness/plugin bundle profile.
-- `anthropics/skills`: standard Agent Skills profile.
-- `wshobson/agents`: marketplace/plugin profile.
-- `VoltAgent/awesome-agent-skills`: catalog profile.
-
-Bad design:
-
-- `if repo === "mattpocock/skills"` branches in the import logic;
-- repo-specific policy decisions embedded in TypeScript;
-- automatic global activation because a known repository was installed.
-
-## Import Output Contract
-
-Every profile or detector should output the same normalized shape:
-
-- install units;
-- declared skills;
-- owner links via `owner_install_unit`;
-- component lists;
-- guessed capabilities;
-- default invocation and exposure;
-- warnings and decisions requiring user approval.
-
-Current CLI surface:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --out .skillboard/reports/import-fragment.yaml
-```
-
-The command emits a config fragment rather than mutating policy automatically.
-This keeps the control plane reviewable while still avoiding hardcoded adapter
-branches.
-
-When the fragment is acceptable, the same importer can merge it:
-
-```bash
+
+3. Detector plugins
+
+   Code adapters are only for sources whose layout cannot be described
+   declaratively, such as installers that mutate multiple config files or require
+   command output parsing. These should be small detector modules that produce the
+   same install-unit data model as profiles.
+
+## Built-In Profiles Are Not Hardcoding
+
+SkillBoard can ship built-in profiles for popular ecosystems, but they should be
+treated as bundled data, not product logic. Users and communities should be able
+to add or override profiles without forking the CLI.
+
+Good built-ins:
+
+- `mattpocock/skills`: skill pack profile.
+- `code-yeongyu/oh-my-openagent`: harness/plugin bundle profile.
+- `anthropics/skills`: standard Agent Skills profile.
+- `wshobson/agents`: marketplace/plugin profile.
+- `VoltAgent/awesome-agent-skills`: catalog profile.
+
+Bad design:
+
+- `if repo === "mattpocock/skills"` branches in the import logic;
+- repo-specific policy decisions embedded in TypeScript;
+- automatic global activation because a known repository was installed.
+
+## Import Output Contract
+
+Every profile or detector should output the same normalized shape:
+
+- install units;
+- declared skills;
+- owner links via `owner_install_unit`;
+- component lists;
+- guessed capabilities;
+- default invocation and exposure;
+- warnings and decisions requiring user approval.
+
+Current CLI surface:
+
+```bash
+skillboard import \
+  --profile github.mattpocock.skills \
+  --source-root /path/to/source \
+  --out .skillboard/reports/import-fragment.yaml
+```
+
+The command emits a config fragment rather than mutating policy automatically.
+This keeps the control plane reviewable while still avoiding hardcoded adapter
+branches.
+
+When the fragment is acceptable, the same importer can merge it:
+
+```bash
 skillboard import \
   --profile github.mattpocock.skills \
   --source-root /path/to/source \
@@ -116,12 +116,12 @@ skillboard import \
 Merge is append-only by default and refuses duplicate skill or install-unit ids.
 `--replace` is the explicit overwrite escape hatch. Drop `--dry-run` after
 reviewing the change plan.
-
-The reconciler then applies the same policy rules regardless of source.
-
-## Default Safety
-
-New external skills should default to `vendor` or `candidate`, with
-`manual-only` or `router-only` invocation. Personal control skills can become
-`global-meta`, but external repositories should not gain `global-auto` through an
-adapter.
+
+The reconciler then applies the same policy rules regardless of source.
+
+## Default Safety
+
+New external skills should default to `vendor` or `candidate`, with
+`manual-only` or `router-only` invocation. Personal control skills can become
+`global-meta`, but external repositories should not gain `global-auto` through an
+adapter.

package/docs/ai-skill-routing-goal.md

@@ -0,0 +1,112 @@
+# AI Skill Routing Goal
+
+SkillBoard's product goal is to be a **non-blocking AI skill routing control plane**. It should help an AI decide which skills and workflow policies apply to the current task without turning normal work into a settings session.
+
+This document is the goal reference for product work, routing changes, AI-facing brief changes, bridge updates, policy UX, and workflow UX.
+
+## Core principle
+
+SkillBoard should keep the user's work moving by default.
+
+The preferred loop is:
+
+```text
+observe → route → work → explain briefly → ask after → remember policy
+```
+
+That means:
+
+1. **Observe** the user's request and current workflow context.
+2. **Route** to the most appropriate allowed skill or workflow policy without asking first when the risk is low.
+3. **Work** normally so SkillBoard does not become a pre-task settings checklist.
+4. **Explain briefly** which skill was used or skipped, only at the level needed for trust.
+5. **Ask after** the task when the routing choice was ambiguous, recurring, or likely to become a useful preference.
+6. **Remember policy** as usage guidance for future turns.
+
+## Non-goals
+
+SkillBoard does not rewrite `SKILL.md` bodies as the primary way to improve outcomes.
+
+SkillBoard should not:
+
+- ask users to choose from a large skill inventory before ordinary work can begin;
+- require users to memorize the SkillBoard command loop;
+- infer permission from raw installed `SKILL.md` files;
+- silently let overlapping skills contaminate an answer;
+- mutate skill body content when a usage policy would solve the problem;
+- turn every allowed skill invocation into a permission prompt.
+
+## What SkillBoard controls
+
+SkillBoard controls **when and how a skill may influence an AI workflow**.
+
+The control object is a usage policy, not the skill body itself:
+
+- task or intent triggers;
+- workflow scope;
+- user, project, or team scope;
+- preferred and fallback skills;
+- exclusion rules;
+- confidence or ambiguity thresholds;
+- disclosure and guard behavior;
+- pending policy suggestions to review later.
+
+## Skill usage modes
+
+Use these terms when designing routing, docs, brief output, or policy UX:
+
+- **Always use** — apply the skill automatically for a clearly scoped situation.
+- **Prefer** — choose this skill first when several skills match.
+- **Reference only** — read the skill as background guidance, but do not let its format or workflow dominate the final answer.
+- **Ask after use** — use the skill for low-risk ambiguous work, then ask whether to remember that choice.
+- **Ask before use** — ask first only when the action is risky, policy-changing, expensive, destructive, or externally visible.
+- **Avoid** — do not use the skill in a scoped situation unless the user explicitly asks.
+- **Block** — never use the skill while the policy remains in force.
+
+## User-facing flow
+
+A normal user should be able to talk to their AI naturally:
+
+```text
+User: "Help me refine this UX flow."
+AI: works using the routed skills.
+AI: "I used command-flow-ux-audit as the primary reference and left TDD skills out because this was not a code-editing task. Should I treat that as the default for UX-flow requests?"
+```
+
+The confirmation is intentionally small and late. It records a policy preference without interrupting the work that caused the user to ask for help.
+
+## AI-facing behavior
+
+AI integrations should:
+
+- read the current SkillBoard brief before making skill availability claims;
+- route from the current request and workflow instead of searching raw skill bodies;
+- run the guard automatically immediately before invoking an allowed skill;
+- disclose allowed skill use at the start and completion;
+- ask the user before applying policy-changing action cards;
+- reread the post-apply brief before making another availability claim;
+- propose remembered policy only when the user has seen enough context to judge the result.
+
+## Development rule
+
+Read `docs/ai-skill-routing-goal.md` before changing routing, brief, bridge, policy, or workflow UX.
+
+Any implementation that affects AI-mediated skill selection should preserve the non-blocking loop:
+
+```text
+observe → route → work → explain briefly → ask after → remember policy
+```
+
+When in doubt, prefer a small usage-policy change over skill-body mutation or a larger pre-task setup flow.
+
+## MVP acceptance criteria
+
+A change moves SkillBoard toward this goal when:
+
+- ordinary allowed-skill work proceeds without a pre-task skill-selection prompt;
+- ambiguous but low-risk choices can be handled with ask-after-use policy suggestions;
+- risky or policy-changing actions still require explicit confirmation before apply;
+- `brief --json` gives AI integrations a stable way to discover the goal document and routing guidance;
+- text output stays compact by default and reserves verbose detail for explicit requests;
+- users can understand why a skill was used, skipped, or blocked;
+- SkillBoard records usage policy separately from skill body content.

package/docs/capabilities.md

@@ -76,6 +76,12 @@ workflow.required_capabilities
 
 If no preferred skill is set in the workflow, the global catalog's canonical skill is used. Fallbacks are checked in order: first the workflow's own fallback list, then the global alternatives.
 
+## Explicit Skill Variants
+
+Use `skillboard variant add claude.a --from a --capability task-review --workflow claude-workflow --path claude/a ...` to record a user-approved `a -> claude.a` variant. SkillBoard adds the variant to the capability alternatives, makes it preferred for the named workflow, and keeps the base skill available as fallback.
+
+This is policy registration, not prompt migration. For a reviewed manual adaptation lifecycle, run `skillboard variant fork <variant-id>` to create a draft and raw snapshot, edit the variant body by hand, inspect `skillboard variant status <variant-id>` for `variant.status` and computed drift, then use `skillboard variant approve <variant-id>` or `skillboard variant reset <variant-id>`. SkillBoard records user-approved variants and consistent workflow policy across agents; it does not convert skill bodies, does not rewrite skill bodies, and does not guarantee semantic equivalence of skill bodies.
+
 ## Global vs Workflow: When to Use Each
 
 | Use case | Use global catalog | Use workflow requirement |