skill-system-installer

What this skill does

# Skill Installer

Installer and deploy surface for the skill system.

Public contract:

- Use `sk init` (`skill-system-cli`) as the primary bootstrap entrypoint for this repository.
- Use `sk install deploy --target <path>` for advanced sidecar attachment into external projects.
- `scripts/skills.sh` remains the implementation backend for installer/deploy operations.

## Project-Scoped DB/MCP Guidance

- PostgreSQL-backed skills should follow project-scoped DB targeting (`<project>-memory`) by auto-detection.
- Do not rely on shell-global `SKILL_PGDATABASE`; prefer project-local overrides only when required.
- Do not allow ambient `PGDATABASE` to silently steer skill runtime DB targets.
- MCP server entries should use absolute skill paths in globally-installed setups.

Use the helper scripts based on the task:
- List curated skills when the user asks what is available, or if the user uses this skill without specifying what to do.
- Install from the curated list when the user provides a skill name.
- Install from another repo when the user provides a GitHub repo/path (including private repos).

Install skills with the helper scripts.

## Bootstrap (First-Run)

Run `scripts/skills.sh bootstrap` to detect and scaffold the skill system:

1. **Detect** missing structure: `config/`, `note/`, `.tkt/`, `skills-lock.json`
2. **Scaffold** any missing directories with stub files
3. **Compute** hashes for any `"pending"` entries in `skills-lock.json`
4. **Validate** all installed skills have `SKILL.md`
5. **Check** dependencies (`python3`, `git`, `bash`)

```bash
scripts/skills.sh bootstrap
# or via sk CLI:
sk install bootstrap
```

Output is JSON with `checks` (what was found) and `actions_taken` (what was created).

This is idempotent — safe to run multiple times. Agents should run it when they detect the skill system is partially initialized or when a user asks to set up skills.

## Communication

When listing curated skills, show available names and which ones are already installed in the current scope.

## Scripts

All of these scripts use network, so when running in the sandbox, request escalation when running them.

- `scripts/list-curated-skills.py` (prints curated list with installed annotations)
- `scripts/list-curated-skills.py --format json`
- `scripts/skills.sh` (unified wrapper for install, list, update, sync, deploy)
- `scripts/skills.sh doctor --target <path>` (detect-only preflight checks)
- `scripts/skills.sh deploy --target <path> [--mode minimal|local|full] [--no-dashboard]` (sidecar deploy into a target project; dashboard generated by default)
- `scripts/skills.sh dashboard --target <path>` (generate target dashboard/index.html)
- `scripts/skills.sh host-shell <bootstrap|discover|compat|doctor> [--target <path>]` (thin host plugin shell MVP)
- `scripts/install-skill-from-github.py --repo <owner>/<repo> --path <path/to/skill> [<path/to/skill> ...]`
- `scripts/install-skill-from-github.py --url https://github.com/<owner>/<repo>/tree/<ref>/<path>`
- `scripts/update-skills.py --all`
- `scripts/update-skills.py --skill <skill-name> [--update] [--dry-run]`

## Doctor (Preflight)

Run `scripts/skills.sh doctor --target /path/to/project` to inspect a target project without modifying it.

Doctor reports:
- target existence, directory type, and writability
- git binary/repo signal
- required structure presence (`config/`, `note/`, `.tkt/`, `skills-lock.json`)
- sidecar skill-system footprint for deployed projects
- dashboard presence (`dashboard/index.html`) and dashboard generator skill entrypoint
- optional database readiness signal (env/config + psql availability)

Output shape:
- `status`
- `target`
- `checks`
- `recommended_actions`
- `healthy`

## Dashboard (Target Render)

Run `scripts/skills.sh dashboard --target /path/to/project` to generate a dashboard for a target project.

Dashboard generation behavior:
- reuses `skills/skill-system-dashboard/scripts/generate.py` as the single rendering source
- reads target project context (`skills/`, `.tkt/`, `.memory/`, and optional `.env`/`.env.local` database URL)
- writes output to `<target>/dashboard/index.html` by default
- tolerates missing target structures by rendering empty sections instead of failing
- returns structured JSON (including `status`, `output`, and `target`)
- includes one-click launch guidance mapping `/SK-dashboard` to `sk dashboard`

## Deploy (Sidecar)

Run `scripts/skills.sh deploy --target /path/to/project [--mode minimal|local|full] [--no-dashboard]` to deploy the current skill-system repo as a sidecar into a target project.

Deploy behavior:
- creates or reuses target `.skill-system/` as the managed sidecar root
- copies skill-system assets into the sidecar without overwriting existing sidecar files
- scaffolds missing target `config/`, `note/`, `.tkt/`, and `skills-lock.json`
- links mutable target state back into the sidecar so sidecar tools operate on target project state
- ensures target `skills` resolves to sidecar `skills` for existing CLI/dashboard path expectations
- generates dashboard/index.html by default; use `--no-dashboard` to skip
- runs `doctor --target` after deployment and returns a health summary
- emits `dashboard_onboarding` payload fields so users can run `/SK-dashboard` or the equivalent CLI command immediately

## Thin Host Plugin Shell MVP

The installer ships a minimal host-shell adapter to validate composition boundaries without taking ownership from existing modules.

Entry:

```bash
scripts/skills.sh host-shell bootstrap --target /path/to/project
scripts/skills.sh host-shell discover --target /path/to/project
scripts/skills.sh host-shell compat
scripts/skills.sh host-shell doctor --target /path/to/project
```

Boundary guarantees:

- Memory remains module-first (`mem.py` + MCP). Plugin behavior is optional adapter logic.
- Control-plane ownership remains with `skill-system-tkt` and `skill-system-review`.
- Planning ownership remains with `skill-system-workflow`.
- Graph/dashboard/debug ownership remains with their existing modules.

This is intentionally an MVP shell and not a platform redesign.

## Update

Use `scripts/update-skills.py` to compare installed skill directories with hashes from `skills-lock.json`.

- `--all` checks every locked skill; `--skill <name>` checks one skill.
- Add `--update` to reinstall missing/drifted skills and refresh `computedHash`.
- Add `--dry-run` to report planned updates without making changes.
- `--preserve-insight/--no-preserve-insight` controls local insight-preservation merge behavior (`--preserve-insight` default true).
- Optional: `--lockfile <path>` and `--skills-dir <path>`.

When update runs with preserve mode enabled, the installer performs a 3-way merge:

`original baseline -> local modified -> upstream new`

Conflicts are never auto-merged. Conflict markers are written for user review.

## Behavior and Options

- Defaults to direct download for public GitHub repos.
- If download fails with auth/permission errors, falls back to git sparse checkout.
- Aborts if the destination skill directory already exists unless `--force` is set.
- Global installs use `$SKILLS_GLOBAL_HOME/skills/<skill-name>` (default `~/.skills-system/skills`).
- Multiple `--path` values install multiple skills in one run, each named from the path basename unless `--name` is supplied.
- Options: `--ref <ref>` (default `main`), `--dest <path>`, `--method auto|download|git`, `--force`.

## Notes

- Curated listing is fetched from `https://github.com/openai/skills/tree/main/skills/.curated` via the GitHub API. If it is unavailable, explain the error and exit.
- Private GitHub repos can be accessed via existing git credentials or optional `GITHUB_TOKEN`/`GH_TOKEN` for download.
- Git fallback tries HTTPS first, then SSH.
- Installed annotations come from scoped skill directories (`$SKILLS_GLOBAL_HOME/skills` and project-local `skills/`).

```skill-manifest
{
  "schema_version": "2.0",
  "id": "skill-system-installer",
  "version":