skill-system-installer

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)

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:

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/).

{
  "schema_version": "2.0",
  "id": "skill-system-installer",
  "version": "1.0.0",
  "capabilities": ["skill-install", "skill-list", "skill-update", "skill-status", "skill-sync", "skill-bootstrap", "skill-doctor", "skill-dashboard", "skill-deploy"],
  "effects": ["net.fetch", "fs.write", "fs.read", "proc.exec"],
  "operations": {
    "bootstrap": {
      "description": "First-run setup: detect missing structure, scaffold directories, compute pending lockfile hashes, validate skills.",
      "input": {},
      "output": {
        "description": "Bootstrap report with checks and actions taken",
        "fields": { "checks": "object", "actions_taken": "array" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "bootstrap"]
      }
    },
    "doctor": {
      "description": "Detect-only preflight checks for a target project. Reports readiness and recommended actions without changing files.",
      "input": {
        "target": { "type": "string", "required": false, "default": ".", "description": "Target project directory to inspect" }
      },
      "output": {
        "description": "Preflight report",
        "fields": {
          "status": "ok | error",
          "target": "string",
          "checks": "object",
          "recommended_actions": "array",
          "healthy": "boolean"
        }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "doctor", "--target", "{target}"]
      }
    },
    "dashboard": {
      "description": "Generate target dashboard/index.html using target project context and tolerant empty-section rendering.",
      "input": {
        "target": { "type": "string", "required": false, "default": ".", "description": "Target project directory" }
      },
      "output": {
        "description": "Dashboard generation report",
        "fields": {
          "status": "ok | error",
          "output": "string",
          "target": "string"
        }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "dashboard", "--target", "{target}"]
      }
    },
    "deploy": {
      "description": "Deploy the current skill-system repo as a sidecar into a target project and report post-deploy health.",
      "input": {
        "target": { "type": "string", "required": true, "description": "Target project directory" },
        "mode": { "type": "string", "required": false, "default": "full", "description": "Bootstrap profile: minimal, local, or full" },
        "dashboard": { "type": "boolean", "required": false, "default": false, "description": "Generate dashboard/index.html after deploy" }
      },
      "output": {
        "description": "Deploy report with paths, actions taken, and doctor health summary",
        "fields": {
          "status": "ok | error",
          "target": "string",
          "sidecar": "string",
          "deployed_paths": "object",
          "actions_taken": "array",
          "health_summary": "object"
        }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "deploy", "--target", "{target}", "--mode", "{mode}"]
      }
    },
    "list": {
      "description": "List available curated skills with installed annotations and show local/global installed skills.",
      "input": {
        "format": { "type": "string", "required": false, "default": "text", "description": "Output format: text or json" }
      },
      "output": {
        "description": "List of curated skills with install status",
        "fields": { "skills": "array of {name, installed}" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/list-curated-skills.py", "--format", "{format}"],
        "windows": ["python", "scripts/list-curated-skills.py", "--format", "{format}"]
      }
    },
    "install": {
      "description": "Install a skill from GitHub repo path. The scripts/skills.sh wrapper provides a scoped alternative entrypoint.",
      "input": {
        "repo": { "type": "string", "required": true, "description": "GitHub owner/repo" },
        "path": { "type": "string", "required": true, "description": "Path to skill within repo" }
      },
      "output": {
        "description": "Installed skill path",
        "fields": { "installed_path": "string" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/install-skill-from-github.py", "--repo", "{repo}", "--path", "{path}"],
        "windows": ["python", "scripts/install-skill-from-github.py", "--repo", "{repo}", "--path", "{path}"],
        "unix_wrapper": ["bash", "scripts/skills.sh", "install", "--repo", "{repo}", "--path", "{path}"]
      }
    },
    "update": {
      "description": "Check skill drift against lockfile and optionally update drifted skills.",
      "input": {
        "scope": { "type": "string", "required": true, "description": "Either all or one" },
        "skill": { "type": "string", "required": false, "description": "Skill name when scope is one" },
        "apply": { "type": "boolean", "required": false, "default": false, "description": "Apply updates when true" },
        "dry_run": { "type": "boolean", "required": false, "default": false, "description": "Report only" },
        "preserve_insight": { "type": "boolean", "required": false, "default": true, "description": "Preserve local insight edits via 3-way merge with conflict markers" }
      },
      "output": {
        "description": "Drift report and optional update actions",
        "fields": { "status": "ok | error", "table": "skill_name/local_hash/lock_hash/status" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/update-skills.py", "--all"],
        "windows": ["python", "scripts/update-skills.py", "--all"]
      }
    },
    "status": {
      "description": "Report drift/version status and spec-compatibility warnings.",
      "input": {
        "scope": { "type": "string", "required": false, "description": "global or local", "default": "local" },
        "skill": { "type": "string", "required": false, "description": "Optional skill name" }
      },
      "output": {
        "description": "Status rows with warning details",
        "fields": { "status": "ok | error", "skills": "array" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "status"],
        "windows": ["bash", "scripts/skills.sh", "status"]
      }
    },
    "sync": {
      "description": "Synchronize global skills into the local workspace.",
      "input": {
        "strategy": { "type": "string", "required": false, "default": "copy", "description": "Sync strategy: copy or symlink" },
        "force": { "type": "boolean", "required": false, "default": false, "description": "Overwrite existing local skills when true" },
        "skills": { "type": "string", "required": false, "description": "Comma-separated skill names" }
      },
      "output": {
        "description": "Sync report and updated local lockfile",
        "fields": { "status": "ok | error", "skills": "array of synced or skipped skill names" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/skills.sh", "sync"]
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false
  }
}