agent-skillboard 0.1.2 → 0.2.2

package/docs/install.md

@@ -1,34 +1,52 @@
-# Install And Bootstrap
-
-SkillBoard sits one layer above skill installers, plugin marketplaces, harness
-bundles, and local skill repositories.
-
+# Install And Bootstrap
+
+SkillBoard sits one layer above skill installers, plugin marketplaces, harness
+bundles, and local skill repositories.
+
+After install, ask your AI questions like "what skills can you use in this
+project?" or "can you make this reviewed skill available for the current
+workflow?" The AI runs SkillBoard behind the scenes: it reads the current brief,
+uses one current action id only after confirmation when policy would change, and
+runs the guard automatically before actual skill use. For already-allowed
+skills, the AI should tell you which skill it is about to use and which skill it
+used in the result instead of asking for another approval. That disclosure is an
+audit trace, not a permission prompt. You do not need to memorize the SkillBoard
+command loop.
+
 ## Install From npm
 
-Use npx when you want to bootstrap a project without keeping a global
-SkillBoard binary installed:
+Use no-prompt npx package execution when you want to bootstrap a project
+without keeping a global SkillBoard binary installed:
+
+AI/automation/operator details:
 
 ```bash
-npx agent-skillboard init
-npx agent-skillboard brief
-npx agent-skillboard doctor --summary
+npx --yes --package agent-skillboard skillboard init
+npx --yes --package agent-skillboard skillboard doctor --summary
+npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
 SkillBoard does not make installed skills automatically callable. It imports
 trusted local skills as manual-only and keeps runtime/plugin skills quarantined
-until reviewed.
+until their source is reviewed. The brief presents unreviewed runtime sources as
+one-time review decisions rather than default block recommendations; after
+review, individual quarantined skills can be activated as manual-only workflow
+skills. When `init` creates or discovers workflows, use one of the workflow names
+it prints for the first brief. If `init` does not print a workflow, run the unscoped `brief` command it prints instead. The explicit package/binary spelling
+avoids an extra npx install prompt and keeps the executable name clear.
 
-In CI or scripts, use the explicit package/binary spelling:
+The equivalent `npm exec` spelling is also no-prompt and works well in scripts:
 
 ```bash
-npx --yes --package agent-skillboard skillboard init
-npx --yes --package agent-skillboard skillboard doctor --summary
 npm exec --yes --package agent-skillboard -- skillboard init
 npm exec --yes --package agent-skillboard -- skillboard doctor --summary
+npm exec --yes --package agent-skillboard -- skillboard brief --workflow <workflow-from-init>
 ```
 
 For repeated local use, install the CLI globally:
 
+AI/automation/operator details:
+
 ```bash
 npm install -g agent-skillboard
 skillboard init
@@ -43,10 +61,12 @@ The executable remains `skillboard` even though the npm package name is
 Use GitHub npx only when you intentionally want the current repository state
 before the next npm release:
 
+AI/automation/operator details:
+
 ```bash
 npx --yes --package github:NyXXiR/skillboard skillboard init
-npx --yes --package github:NyXXiR/skillboard skillboard brief
 npx --yes --package github:NyXXiR/skillboard skillboard doctor --summary
+npx --yes --package github:NyXXiR/skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
 The equivalent `npm exec` spelling is explicit about the package and binary:
@@ -54,35 +74,38 @@ The equivalent `npm exec` spelling is explicit about the package and binary:
 ```bash
 npm exec --yes --package github:NyXXiR/skillboard -- skillboard init
 npm exec --yes --package github:NyXXiR/skillboard -- skillboard doctor --summary
+npm exec --yes --package github:NyXXiR/skillboard -- skillboard brief --workflow <workflow-from-init>
 ```
 
 ## Install From A Clone
 
 Use a clone when developing SkillBoard itself or testing unreleased changes:
 
+AI/automation/operator details:
+
 ```bash
 git clone https://github.com/NyXXiR/skillboard.git
 cd skillboard
 npm install
 node bin/skillboard.mjs init --dir /path/to/your/project
-node bin/skillboard.mjs brief --dir /path/to/your/project
 node bin/skillboard.mjs doctor --dir /path/to/your/project --summary
+node bin/skillboard.mjs brief --dir /path/to/your/project --workflow <workflow-from-init>
 ```
-
-## What init Does
-
+
+## What init Does
+
 `skillboard init` is the safe mutating step. npm installation itself does not
 modify a project, but init creates the files that let agents discover the control
 plane without a manual prompt and inventories already installed local agent
 skills.
-
-Created project files:
-
-- `skillboard.config.yaml`: desired state for workflows, capabilities, skills,
-  harnesses, and install units.
-- `skills/`: local skill root.
-- `.skillboard/reports/`: generated dashboard and reconcile output location.
-- `.skillboard/profiles/`: project-specific source profile location.
+
+Created project files:
+
+- `skillboard.config.yaml`: desired state for workflows, capabilities, skills,
+  harnesses, and install units.
+- `skills/`: local skill root.
+- `.skillboard/reports/`: generated dashboard and reconcile output location.
+- `.skillboard/profiles/`: project-specific source profile location.
 - `AGENTS.md`: Codex-style project instruction bridge.
 - `CLAUDE.md`: Claude Code project instruction bridge.
 
@@ -97,12 +120,16 @@ manual-only` and attached to a generated local manual workflow when the project
 has no workflow metadata yet. That lets a first-time user keep their existing
 manual skills usable through `skillboard can-use` and guard checks without
 granting automatic model invocation or creating legacy-state warning noise.
-System, plugin, and other runtime-supplied skills are written with `status: quarantined` and
-`invocation: blocked`. Plugin hooks, MCP servers, commands, and modified config files are
-recorded on the owning install unit when manifest metadata exposes them, which
-lets policy checks flag high-risk runtime extensions without flattening them
-into loose skills. Use `--no-scan-installed` for a scaffold-only bootstrap, or
-`--scan-root <dir>[,<dir>]` to add server-specific skill roots during bootstrap.
+System, plugin, and other runtime-supplied skills are written with `status:
+quarantined` and `invocation: blocked`. Plugin hooks, MCP servers, commands, and
+modified config files are recorded on the owning install unit when manifest
+metadata exposes them, which lets policy checks flag high-risk runtime
+extensions without flattening them into loose skills. After the owning source is
+reviewed, action cards can activate a quarantined runtime skill into a workflow
+as `manual-only`; automatic preference should still be remembered later through
+the normal ask-after-use policy loop. Use `--no-scan-installed` for a
+scaffold-only bootstrap, or `--scan-root <dir>[,<dir>]` to add server-specific
+skill roots during bootstrap.
 
 After init, run:
 
@@ -120,16 +147,30 @@ CI or automation gate. Use `--json` for an agent-readable health payload, or
 report. `skillboard status` is the same report under a shorter command name.
 
 For AI-mediated use, the generated bridge tells agents to answer availability
-questions from `skillboard brief --json`, not from memory or from raw
-`SKILL.md` bodies. The brief is read-only and organizes the response around
-"What your AI can use now", decisions the user can make once, hard safety
-blocks, inactive installed skills, and suggested action cards. Text briefs show
-action cards by default; JSON keeps them opt-in with `--include-actions`. The
-default text brief is compact for large skill sets: it keeps counts, top
-categories, the next safe action, short section previews, and short action
-summaries. Use `skillboard brief --verbose` when you need the full list or full
-copyable command details. Agents should still run `skillboard guard use ...`
-immediately before an actual skill invocation.
+questions by reading the current brief with `skillboard brief --json`, not from
+memory or from raw `SKILL.md` bodies. The brief is read-only and organizes the
+response around "What your AI can use now", decisions the user can make once,
+hard safety blocks, inactive installed skills, and suggested action cards. Text
+briefs show action cards by default; JSON keeps them opt-in with
+`--include-actions`. The default text brief is compact for large skill sets: it
+keeps counts, top categories, the next safe action, short section previews, and
+short action summaries. Use `skillboard brief --verbose` when an operator needs
+the full list or full copyable command details. Agents should still run
+`skillboard guard use ...` immediately before an actual skill invocation. A
+passing guard is not a user prompt; the agent should disclose the selected skill
+at the start and completion, and ask only if the guard denies use or a
+policy-changing action is needed.
+
+When the user asks which skill fits a task, the bridge tells agents to use
+`skillboard brief --intent <request> --json`, read `assistant_guidance.route`,
+and use `recommended_skill`, `fallback_skills`, `route_candidates`,
+`post_use_policy_suggestion`, and `guard_command` instead of guessing from raw
+skill text. Inspect
+`route_candidates` when several skills match so denied candidates and selected
+fallbacks are clear. If `post_use_policy_suggestion` is present, the agent
+should use the allowed routed skill first, then ask after completion whether to
+remember the suggested policy. If no skill matches, the agent should ask a
+clarifying question before choosing a skill.
 
 Action cards are change suggestions. Before an agent applies one that changes
 policy, trust, hooks, reset state, or skill references, it should request user
@@ -142,7 +183,10 @@ so stale action ids and cached action-card shell text are not replayed.
 For hook action cards specifically, keep `apply-action` as the action-card
 primary flow. Raw `skillboard hook install ... --dry-run --json` previews and
 the matching non-dry-run command are underlying manual detail for operators who
-need to inspect or materialize an executable guard hook directly.
+need to inspect or materialize an executable guard hook directly. Generated hooks
+pin the install-time SkillBoard command, config, skills root, and workflow; set
+those values with hook install options such as `--skillboard-bin`, not with
+runtime environment overrides.
 
 ## Hermes System Prompt Bridge
 
@@ -152,20 +196,34 @@ system prompt for the managed project:
 
 ```text
 Use SkillBoard as the source of truth for agent skill availability.
-Before answering what skills can be used, run:
-skillboard brief --json --dir /path/to/your/project
+Use the workflow generated by init, such as `hermes-codex-local-manual`, or a
+workflow you explicitly created for that Hermes profile.
+
+Before answering what skills can be used in that workflow, run:
+skillboard brief --workflow <workflow-name> --json --include-actions --dir /path/to/your/project
+
+When the user asks which skill fits a task, run:
+skillboard brief --workflow <workflow-name> --intent <request> --json --dir /path/to/your/project
+Read assistant_guidance.route. Use recommended_skill, fallback_skills,
+route_candidates, post_use_policy_suggestion, and guard_command. Inspect
+route_candidates when several skills match so denied candidates and selected
+fallbacks are clear. If post_use_policy_suggestion is present, use the allowed
+routed skill first, then ask after completion whether to remember the suggested
+policy. If no skill matches, ask a clarifying question before choosing a skill.
 
 Do not infer availability from installed SKILL.md files. Immediately before
 invoking a skill, run:
 skillboard guard use <skill-id> --workflow <workflow-name> --dir /path/to/your/project
 
-For suggested policy changes, ask the user to approve one current action id,
-then run:
-skillboard apply-action <action-id> --dir /path/to/your/project --yes --json
-```
+If the guard allows an already-approved skill, do not ask the user for another
+approval. Say at the start: "I will use <skill-id> for this request." Say at
+completion: "I used <skill-id> for this request." Treat that disclosure as an
+audit trace, not a permission prompt.
 
-Use the workflow generated by init, such as `hermes-codex-local-manual`, or a
-workflow you explicitly created for that Hermes profile.
+For suggested policy changes, ask the user to approve one current action id from
+the `--include-actions` brief, then run:
+skillboard apply-action <action-id> --workflow <workflow-name> --dir /path/to/your/project --yes --json
+```
 
 After installing a new local agent skill pack, plugin, workflow bundle, or
 harness, rescan before enabling anything:
@@ -275,24 +333,24 @@ may be wired into local agent/runtime configuration. Combine `--reset-config`,
 SkillBoard-owned lifecycle scaffolding while preserving local `skills/`.
 
 ## Upper-Layer Control
-
-After installing skill packs or harness bundles, represent them as install
-units:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/mattpocock-skills \
-  --out .skillboard/reports/mattpocock-import.yaml
-```
-
-The import output is a reviewable YAML fragment. Merge the accepted `skills` and
-`install_units` into `skillboard.config.yaml`; imported skills stay inactive
-until workflows and policies explicitly use them.
-
-For a direct but still safe apply path:
-
-```bash
+
+After installing skill packs or harness bundles, represent them as install
+units:
+
+```bash
+skillboard import \
+  --profile github.mattpocock.skills \
+  --source-root /path/to/mattpocock-skills \
+  --out .skillboard/reports/mattpocock-import.yaml
+```
+
+The import output is a reviewable YAML fragment. Merge the accepted `skills` and
+`install_units` into `skillboard.config.yaml`; imported skills stay inactive
+until workflows and policies explicitly use them.
+
+For a direct but still safe apply path:
+
+```bash
 skillboard import \
   --profile github.mattpocock.skills \
   --source-root /path/to/mattpocock-skills \
@@ -320,50 +378,50 @@ skillboard review install-unit github.mattpocock.skills \
 
 Automatic invocation remains blocked for unreviewed non-user sources. The user
 experience should still be a one-time decision queue: review, trust, or block
-the install unit once, then revisit only when the source, skill, or workflow
-changes.
+the install unit once, activate only the needed quarantined skills as
+manual-only, then revisit only when the source, skill, or workflow changes.
 
 ```yaml
 install_units:
-  github.mattpocock.skills:
-    kind: marketplace
-    source: npx skills@latest add mattpocock/skills
-    scope: user-global
-    provided_components:
-      - skills
-    components:
-      skills:
-        - matt.tdd
-```
-
-Then link each governed skill back to its owner:
-
-```yaml
-skills:
-  matt.tdd:
-    path: matt/tdd
-    status: active
-    invocation: workflow-auto
-    exposure: exported
-    owner_install_unit: github.mattpocock.skills
-```
-
-Run:
-
-```bash
-skillboard check --config skillboard.config.yaml --skills skills
-skillboard dashboard --config skillboard.config.yaml --skills skills --out .skillboard/reports/skill-map.md
-```
-
-This keeps multiple installed repositories visible as managed units instead of
-turning every skill into a global invocation candidate.
-
-## Adapter Direction
-
-Import support should be profile-driven, not hardcoded. A popular source such as
-`mattpocock/skills` or `oh-my-openagent` may ship with a built-in source profile,
-but that profile should be data that maps repository layout and defaults into the
-same install-unit model. Source-specific code should be limited to detector
-plugins for layouts that cannot be described declaratively.
-
-See [adapters.md](adapters.md).
+  github.mattpocock.skills:
+    kind: marketplace
+    source: npx skills@latest add mattpocock/skills
+    scope: user-global
+    provided_components:
+      - skills
+    components:
+      skills:
+        - matt.tdd
+```
+
+Then link each governed skill back to its owner:
+
+```yaml
+skills:
+  matt.tdd:
+    path: matt/tdd
+    status: active
+    invocation: workflow-auto
+    exposure: exported
+    owner_install_unit: github.mattpocock.skills
+```
+
+Run:
+
+```bash
+skillboard check --config skillboard.config.yaml --skills skills
+skillboard dashboard --config skillboard.config.yaml --skills skills --out .skillboard/reports/skill-map.md
+```
+
+This keeps multiple installed repositories visible as managed units instead of
+turning every skill into a global invocation candidate.
+
+## Adapter Direction
+
+Import support should be profile-driven, not hardcoded. A popular source such as
+`mattpocock/skills` or `oh-my-openagent` may ship with a built-in source profile,
+but that profile should be data that maps repository layout and defaults into the
+same install-unit model. Source-specific code should be limited to detector
+plugins for layouts that cannot be described declaratively.
+
+See [adapters.md](adapters.md).