diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3fd83f06..ec63671aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -167,7 +167,7 @@ After changing a router skill or an app command fragment, run: make skills ``` -That target first runs `sol skills build` to regenerate the checked-in references, then refreshes the `sol` + `journal` router skill symlinks inside the journal. `make install` also runs this target, and `make ci` / `make install-checks` runs `sol skills build --check` to catch stale generated references. +That target first runs `scripts/build_skill_references.py` to regenerate the checked-in references, then refreshes the `sol` + `journal` router skill symlinks inside the journal. `make install` also runs this target, and `make ci` / `make install-checks` runs `scripts/build_skill_references.py --check` to catch stale generated references. ## Migrating from a source install to a packaged install diff --git a/docs/APPS.md b/docs/APPS.md index 3a0d3e4a3..436d38b94 100644 --- a/docs/APPS.md +++ b/docs/APPS.md @@ -405,14 +405,14 @@ Context is provided inline in the `.md` body via template variables: ### 10. Router Skills and App Command Fragments -Project installs expose exactly two [Agent Skills](https://agentskills.io/specification): `solstone/talent/sol/` and `solstone/talent/journal/`. App-specific `SKILL.md` files under `solstone/apps//talent//` are command-guidance fragments. They are not installed directly; `sol skills build` folds them into the generated router references. +Project installs expose exactly two [Agent Skills](https://agentskills.io/specification): `solstone/talent/sol/` and `solstone/talent/journal/`. App-specific `SKILL.md` files under `solstone/apps//talent//` are command-guidance fragments. They are not installed directly; `make skills` folds them into the generated router references via `scripts/build_skill_references.py`. **Key Points:** - Installed router skill directories live at `solstone/talent/sol/` and `solstone/talent/journal/`. - App command fragments live at `solstone/apps//talent//SKILL.md`. - The fragment directory name must match the `name` field in the YAML frontmatter. -- `make skills` runs `sol skills build`, then installs only the `sol` and `journal` router skill symlinks into `journal/.agents/skills/` and `journal/.claude/skills/`. -- `make ci` / `make install-checks` runs `sol skills build --check` and fails if generated references are stale. +- `make skills` runs `scripts/build_skill_references.py`, then installs only the `sol` and `journal` router skill symlinks into `journal/.agents/skills/` and `journal/.claude/skills/`. +- `make ci` / `make install-checks` runs `scripts/build_skill_references.py --check` and fails if generated references are stale. - Router skills and app fragments are standalone from the talent agent/generator system; the talent loader ignores subdirectories. **Router skill directory structure:** @@ -420,7 +420,7 @@ Project installs expose exactly two [Agent Skills](https://agentskills.io/specif talent/sol/ ├── SKILL.md # Required: YAML frontmatter + instructions └── references/ - └── commands.md # Generated by sol skills build + └── commands.md # Generated by make skills (scripts/build_skill_references.py) ``` **SKILL.md format:** diff --git a/docs/SOLCLI.md b/docs/SOLCLI.md index 00446a4e9..d70d51c91 100644 --- a/docs/SOLCLI.md +++ b/docs/SOLCLI.md @@ -109,7 +109,7 @@ This is the happy path for most new commands. 3. **Regenerate the inventory** with `make build-native-sol-inventory`. 4. **Update the app command fragment** (if agents should use these commands). - `sol skills build` discovers these fragments automatically from + `make skills` discovers these fragments via `scripts/build_skill_references.py` from `solstone/apps/*/talent/*/SKILL.md`: ```markdown @@ -140,9 +140,9 @@ List items for a day. - `-f, --facet`: facet name (default: `SOL_FACET` env). ``` -4. **Run `sol skills build`** to regenerate the checked-in router references. `make skills` wraps this and then refreshes the installed `sol` + `journal` router skill symlinks. +4. **Run `make skills`** to regenerate the checked-in router references with `scripts/build_skill_references.py` and refresh the installed `sol` + `journal` router skill symlinks. -5. **Run `sol skills build --check`** before committing, or rely on `make ci` / `make install-checks`. The check fails when generated router references are stale. +5. **Run `make check-skill-references`** before committing, or rely on `make ci` / `make install-checks`. The check invokes `scripts/build_skill_references.py --check` and fails when generated router references are stale. ### Local-only think tools @@ -159,9 +159,9 @@ the journal host and depends heavily on `solstone/think/` internals. |------|-----------|-----------| | `solstone/apps//native/authority.toml` | Native command path, params, and route contract | Yes | | `solstone/apps//native/command.rs` | Native handler implementation | Yes | -| `solstone/apps//talent//SKILL.md` | App command guidance fragment used by `sol skills build` | If agents should use it | -| `solstone/talent/sol/references/commands.md` | Generated `sol call ` inventory | Auto-generated by `sol skills build` | -| `solstone/talent/journal/references/commands.md` | Generated journal-host command guidance | Auto-generated by `sol skills build` | +| `solstone/apps//talent//SKILL.md` | App command guidance fragment used by `scripts/build_skill_references.py` | If agents should use it | +| `solstone/talent/sol/references/commands.md` | Generated `sol call ` inventory | Auto-generated by `make skills` (`scripts/build_skill_references.py`) | +| `solstone/talent/journal/references/commands.md` | Generated journal-host command guidance | Auto-generated by `make skills` (`scripts/build_skill_references.py`) | | `core/fixtures/native-sol/parity/.jsonl` | Native parity vectors | Yes | ## Conventions @@ -420,7 +420,7 @@ CLI commands, a native `native/authority.toml` plus `native/command.rs`. | `awareness` | `solstone/apps/awareness/native/authority.toml` | status, imports, log, log-read | | `journal` | `solstone/think/tools/call.py` | search, events, facets, facet (show/create/update/rename/mute/unmute/delete/merge), news, agents, read, imports, import, retention purge, storage-summary | -`sol skills` builds generated router references and manages coding-agent skill installation. +`sol skills` manages coding-agent skill installation. `make skills` builds generated router references via `scripts/build_skill_references.py` before invoking `sol skills install`. ## Skill System @@ -431,7 +431,7 @@ Project skill installation installs exactly two router skills into both `journal - App command fragments: `solstone/apps//talent//SKILL.md` - Generated references: `solstone/talent/sol/references/commands.md`, `solstone/talent/journal/references/commands.md` -App command fragments are builder source. `sol skills build` folds their guidance into deterministic, checked-in generated references. The generated references aggregate per-app command guidance from native authority files, including health's `sol call health` commands and health's journal-host `journal health` / `journal talent` guidance. There is no in-repo `vit` skill. +App command fragments are builder source. `make skills` folds their guidance into deterministic, checked-in generated references via `scripts/build_skill_references.py`. The generated references aggregate per-app command guidance from native authority files, including health's `sol call health` commands and health's journal-host `journal health` / `journal talent` guidance. There is no in-repo `vit` skill. Fragments document CLI commands and add behavioral guidance beyond what `--help` shows (e.g., "check entity context before attaching a new relationship to avoid duplicates"). Agents consume that guidance through the `sol` and `journal` router skill references. @@ -442,4 +442,4 @@ When you add or change a `sol call` command, update both the native authority/ha - Behavior notes (edge cases, defaults, validation) - Examples showing common usage patterns -Then run `sol skills build` or `make skills`. `sol skills build --check` is wired into `make ci` / `make install-checks` and fails when generated references are stale. +Then run `make skills`. `make check-skill-references` invokes `scripts/build_skill_references.py --check` and is wired into `make ci` / `make install-checks` to fail when generated references are stale. diff --git a/docs/project-structure.md b/docs/project-structure.md index 43f528f1b..b5faa9e57 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -43,5 +43,5 @@ The public `sol` / `solstone` launchers exec `solstone-core`, which routes throu - **Live Logs**: `journal/health/.log` - **Agent Personas**: `solstone/talent/*.md` (apps can add their own talent files under `solstone/apps/*/talent/`, see [docs/APPS.md](docs/APPS.md)) - **Generator Templates**: `solstone/talent/*.md` (apps can add their own talent files under `solstone/apps/*/talent/`, see [docs/APPS.md](docs/APPS.md)) -- **Agent Skills**: `solstone/talent/{sol,journal}/SKILL.md` - the two router skills installed into `journal/.agents/skills/` and `journal/.claude/skills/`; app `SKILL.md` fragments feed generated references via `sol skills build` +- **Agent Skills**: `solstone/talent/{sol,journal}/SKILL.md` - the two router skills installed into `journal/.agents/skills/` and `journal/.claude/skills/`; app `SKILL.md` fragments feed generated references via `make skills` (`scripts/build_skill_references.py`) - **Scratch Space**: `scratch/` - git-ignored local workspace diff --git a/solstone/talent/sol/SKILL.md b/solstone/talent/sol/SKILL.md index 9fdd08dc5..ada2a65ea 100644 --- a/solstone/talent/sol/SKILL.md +++ b/solstone/talent/sol/SKILL.md @@ -93,8 +93,8 @@ sol call support diagnose See [Commands](references/commands.md) for the generated inventory of every `sol call ` command contributed by app skill fragments, including triggers -and read/write/other polarity. Regenerate it with `sol skills build` or -`make skills`; do not inline those command tables here. +and read/write/other polarity. Regenerate it with `make skills` +(`scripts/build_skill_references.py`); do not inline those command tables here. ## Paths