command-code 0.52.4 → 1.0.0

package/dist/bundled/mod-builder/reference/verify.md

@@ -0,0 +1,58 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/mods/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Verify a mod
+
+A mod that fails to import, exports no factory, or throws in its factory becomes a **warning — never a crashed session**. That safety also means a broken mod can fail silently if you never check. This section is the verification loop: load it, list it, exercise it, reload it.
+
+## 1. Load it without installing
+
+```bash
+cmd --mod ./your-mod.ts
+```
+
+`--mod` is repeatable, loads ahead of installed mods, and wins name collisions — the fastest try-it loop. No build step: jiti compiles the TypeScript at load.
+
+## 2. Confirm it registered
+
+```bash
+cmd mods list
+```
+
+Your mod must appear, with no load warnings. If it does not appear, the warning printed by `cmd mods list` says why (import error, no default-export factory, factory threw, duplicate name).
+
+## 3. Exercise every surface it registers
+
+- **Slash command** — type `/` in the chat input: the command must appear in autocomplete with its description. Run it; `{message}` renders an info row, `{prompt}` starts an automated turn.
+- **Tool** — ask the model to use it by name ("call count_todos"). The tool call renders in the feed like any built-in.
+- **Hook** — trigger the behavior it guards (for a `beforeToolCall` blocker, ask for the blocked action and watch the block reason land as the tool result).
+- **Input interception** — type the pattern `transformInput` matches and confirm the rewrite/consume happened.
+- **Status / widget** — the footer segment appears under the input panel; the widget renders around the editor.
+- **Renderer** — `cmd.showEntry` rows render styled; an unregistered type pretty-prints as JSON.
+
+### Test: block-dangerous-commands guards rm -rf
+
+```text copy filename="Prompt"
+Run rm -rf /tmp/scratch-dir
+```
+
+Expected result:
+
+- ✅ The mod's confirm dialog appears before the shell command runs
+- ✅ Declining blocks the tool — the model sees the block reason and adapts
+- ❌ No `tool_running` fires for the blocked call
+
+## 4. Iterate with /reload
+
+Mods load once per process. After editing the file, run `/reload` — it restarts Command Code, resumes the session, and re-discovers and re-imports every mod (jiti caches nothing between loads).
+
+## 5. Headless check (CI)
+
+```bash
+cmd -p "exercise the mod" --mod ./your-mod.ts
+```
+
+Print mode loads user-scope and `--mod` mods with the UI bridge degraded to deterministic defaults (confirm → false, select/input → undefined; timed dialogs resolve `timeoutValue` immediately). A mod that must work in CI should behave sensibly under those defaults.
+
+## Working from the bundled examples
+
+Command Code ships runnable single-file examples inside the bundled `mod-builder` skill — each one loads through the real mod loader in CI on every test run, so copying one is copying something proven to load. In the Command Code repo itself, the same validation is a vitest suite (`packages/harness/src/mod-host/__tests__/examples.test.ts`); if you are contributing an example, that test must stay green.

package/dist/bundled/skill-builder/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: skill-builder
+description: Author a new Agent Skill for Command Code end to end — scaffold the directory, write valid SKILL.md frontmatter, structure the instructions for progressive disclosure, and verify the skill loads. Use when the user wants to create, build, or generate a skill, turn a repeated workflow, prompt, or set of scripts into a reusable skill, or fix a skill that fails validation.
+---
+
+# Skill Builder
+
+You are turning a workflow the user cares about into an Agent Skill: a directory with a
+`SKILL.md` manifest that any agent implementing the Agent Skills standard
+(https://agentskills.io/specification) can discover and load on demand. Follow the steps in
+order; each produces something the next step consumes.
+
+## 1. Pin down the job
+
+Before writing anything, get concrete answers to three questions — from the conversation if
+they are already there, otherwise ask:
+
+- **What does the skill do?** One capability per skill. If the user describes two loosely
+  related jobs (e.g. "release notes and versioning"), propose splitting them.
+- **When should an agent reach for it?** The trigger phrases and task shapes. These become the
+  `description`, which is the only thing the model sees before deciding to load the skill.
+- **What does it need?** Scripts, templates, reference documents, external tools. These decide
+  whether the skill is a single SKILL.md or needs supporting files.
+
+## 2. Choose name and location
+
+Name rules (enforced at load time — a violation means the skill is skipped with a warning):
+
+- 1–64 characters; only lowercase letters `a-z`, digits `0-9`, and hyphens
+- No leading, trailing, or consecutive hyphens
+- **Must equal the directory name** — `my-skill/SKILL.md` declares `name: my-skill`
+
+Prefer a verb-or-domain name that survives out of context: `changelog-writer` beats `helper`.
+
+Location decides who gets the skill:
+
+| Location | Scope |
+|----------|-------|
+| `.commandcode/skills/<name>/` at the project root | everyone in this repo (commit it) |
+| `~/.commandcode/skills/<name>/` | this user, every project |
+| `.agents/skills/<name>/` or `~/.agents/skills/<name>/` | same scopes, shared with other Agent-Skills tools |
+
+Default to the project location when the workflow is repo-specific, the user location when it is
+personal habit. Skills may be grouped in subdirectories (e.g.
+`.commandcode/skills/docs/changelog-writer/`) — discovery is recursive.
+
+## 3. Write the frontmatter
+
+Required fields:
+
+```yaml
+---
+name: changelog-writer
+description: Draft changelog entries from merged PRs and commit history, grouped by change type. Use when the user asks for a changelog, release notes, or "what changed since <version>".
+---
+```
+
+The `description` carries the whole discovery burden. Write it as *what it does* + *when to use
+it*, with the words a user would actually say. Under 1024 characters; two sentences is usually
+right. Avoid "helps with X" — name the verbs and the artifacts.
+
+Optional fields, all standard-compliant:
+
+- `license` — a license name or bundled file reference
+- `compatibility` — only when the skill has real environment requirements (≤500 chars)
+- `metadata` — a string-to-string map for anything else (author, version, …)
+- `allowed-tools` — space-separated pre-approved tools (experimental across implementations)
+
+Command Code also honors these extensions (other tools ignore them safely):
+
+- `argument-hint` — shown in the slash menu, e.g. `argument-hint: "<branch> [--draft]"`
+- `disable-model-invocation: true` — the model never sees or auto-loads the skill; only an
+  explicit `/name` invocation runs it. Use for destructive or highly contextual workflows.
+- `model` — pin a model for the skill's work
+
+## 4. Write the body
+
+The body is the instruction set the agent follows after activation. Structure it for an agent,
+not a human reader: imperative steps, exact commands, decision rules for edge cases, and one
+worked example beat prose paragraphs.
+
+Budget for progressive disclosure — the three-tier loading model the standard defines:
+
+1. **Metadata** (name + description) is always in context. Spend it on triggers.
+2. **The SKILL.md body** loads on activation. Keep it under ~500 lines; if you are pasting long
+   reference material, move it out.
+3. **Supporting files** load only when the body points at them. Link with paths relative to the
+   skill directory: `references/format.md`, `scripts/collect.sh`.
+
+Conventional (not required) subdirectories: `scripts/` for executable helpers, `references/` for
+documentation the agent reads on demand, `assets/` for templates and static files. Positional
+arguments from a slash invocation are available as `$ARGUMENTS` (all of them) or
+`$ARGUMENTS[0]`, `$ARGUMENTS[1]`, … individually.
+
+## 5. Verify
+
+1. Re-read the frontmatter against the rules in step 2 — especially name ↔ directory match.
+2. Run `cmd skills list` (or open `/skills` in the TUI): the skill must appear with no warning.
+   A skipped skill shows up under its failure category — fix and re-check.
+3. Invoke it once with `/name` and confirm the agent follows the body as written. Trim anything
+   it did not need.
+
+If the user will share the skill, remind them: skills are instructions plus executable code, so
+consumers should review the content before trusting it.