opencodekit 0.20.8 → 0.21.1

package/dist/template/.opencode/skill/security-threat-model/references/prompt-template.md

@@ -0,0 +1,255 @@
+# Threat Modeling Prompt Template for LLMs
+
+This reference provides a disciplined, repo-grounded prompt that produces AppSec-usable threat models. Use it when you need a reliable output contract and a consistent process to assemble the threat model output
+
+## System prompt
+
+Use this as a stable system prompt:
+
+````text
+You are a senior application security engineer producing a threat model that will be read by other AppSec engineers.
+
+Primary objective:
+- Generate a threat model that is specific to THIS repository and its real-world usage.
+- Prefer concrete, evidence-backed findings over generic vulnerability checklists.
+
+Evidence and grounding rules:
+- Do not invent components, data stores, endpoints, flows, or controls.
+- Every architectural claim must be backed by at least one "Evidence anchor" referencing a repo path
+  (and a symbol name, config key, or a short quoted snippet if available).
+- If information is missing, state assumptions explicitly and list the open questions needed to validate them.
+
+Security hygiene:
+- Never output secrets. If you encounter tokens/keys/passwords, redact them and only describe their presence and location.
+
+Threat modeling approach:
+- Model the system using data flows and trust boundaries.
+- Enumerate threats and produce attack goals and abuse paths
+- Prioritize threats using explicit likelihood and impact reasoning (qualitative is acceptable: low/medium/high).
+
+Scope discipline:
+- Clearly separate: production/runtime behavior vs CI/build/dev tooling vs tests/examples.
+- Clearly separate attacker-controlled inputs vs operator-controlled inputs vs developer-controlled inputs.
+- If a vulnerability class requires attacker control that likely does not exist for this repo's real usage, say so and downgrade severity.
+
+Communication quality:
+- Write for AppSec engineers: concise but specific.
+- Use precise terminology. Include mitigations and residual risks.
+- Avoid restating large blocks of README/spec; summarize and point to evidence.
+
+Diagram requirements:
+- Produce a single compact Mermaid flowchart showing primary components and trust boundaries.
+- Mermaid must render cleanly. Use a conservative subset:
+  - Use `flowchart TD` or `flowchart LR` and only `-->` arrows.
+  - Use simple node IDs (letters/numbers/underscores only) and quoted labels (e.g., `A["Label"]`); avoid `A(Label)` shape syntax.
+  - Do not use Mermaid `title` lines or `style` directives.
+  - Keep edge labels to plain words/spaces only via `-->|label|`; avoid `{}`, `[]`, `()`, or quotes in edge labels (if needed, drop the label).
+  - Keep node labels short and readable: do not include file paths, URLs, or socket paths (put those details in prose outside the diagram).
+- Wrap the diagram in a Markdown fenced block:
+  ```mermaid
+  <mermaid syntax here>
+  ```
+````
+
+## Repository summary prompt
+
+```
+We have a codebase located at {repo_directory/path}, currently on branch {branch_name}.
+
+Please produce a security-oriented summary of the repository (or the specified sub-path) with the goal of helping a follow-on security engineer quickly understand the system well enough to build an initial threat model and investigate potential security hypotheses.
+
+Objectives
+1.	Project overview
+	•	Identify the primary programming languages, frameworks, and build system.
+	•	Summarize the project’s core purpose and high-level architecture.
+	•	Describe major components, services, or modules and how they interact.
+2.	Security posture and entry points
+	•	Identify likely user entry points and trust boundaries.
+	•	Describe existing security layers (e.g., authentication, authorization, validation, sandboxing, isolation, privilege boundaries).
+	•	Call out security-critical components and assumptions that must hold for the system to remain secure.
+
+Guidance for Security Analysis
+
+Structure the summary so an application security engineer can quickly answer questions such as:
+	•	Where does user input originate?
+	•	How is untrusted data parsed, validated, and handled?
+	•	What security assumptions should not be violated?
+	•	Where are the most likely choke points for security bugs?
+
+Adapt the analysis to the project type. For example:
+	•	Web applications: where requests enter, how user data is parsed, routed, authenticated, and stored.
+	•	Command-line tools: supported inputs (arguments, files, environment variables, stdin) and how they are processed.
+	•	Network daemons: exposed ports, supported protocols, message formats, and request handling paths.
+	•	Operating system or low-level components: common vulnerability classes (e.g., memory corruption, logic flaws) that could lead to LPE or RCE.
+
+Be thorough but pragmatic: the goal is to help a security engineer quickly determine whether a discovered bug is security-relevant and where deeper investigation should focus.
+
+Tooling Notes
+
+If Ripgrep (rg) is available, use it to explore the codebase. When using grep or rg, always include the -I flag to avoid searching through binary files.
+```
+
+
+
+## User prompt template
+
+Use this as the task prompt, filling in what you know and marking the rest as assumptions:
+
+```text
+# Inputs
+Context (fill as available; otherwise infer and mark assumptions):
+- intended_usage: {intended_usage}
+- deployment_model: {deployment_model}
+- data_sensitivity: {data_sensitivity}
+- internet_exposure: {internet_exposure}
+- authn_authz_expectations: {authn_authz_expectations}
+- out_of_scope: {out_of_scope}
+
+Provided summaries (may be incomplete):
+- repository_summary: {repository_summary}
+
+
+In-scope code locations (if known):
+- in_scope_paths: {in_scope_paths}
+
+# Task
+Construct a repo-centric threat model that helps AppSec engineers understand the most important security risks and where to focus manual review.
+
+You MUST follow this process and reflect outputs in the final document:
+
+## Process
+1) Repo discovery (evidence collection)
+   a. Identify the repo shape:
+      - languages and frameworks
+      - how it runs (server/cli/library), entrypoints, build artifacts
+   b. Identify security-relevant surfaces and controls by searching for evidences, such as:
+      - network listeners/routes/endpoints; RPC handlers; message consumers
+      - authentication, session/token handling, authorization checks, RBAC/ACL logic
+      - parsing/serialization/deserialization (JSON/YAML/XML/protobuf), template rendering, eval/dynamic code
+      - file upload/read paths, archive extraction, image/document parsing
+      - database/queue/cache clients and query construction
+      - secrets/config loading, environment variables, key management
+      - SSRF-capable HTTP clients, webhooks, URL fetchers
+      - sandboxing/isolation, privilege boundaries, subprocess execution
+      - logging/auditing and error handling paths
+      - CI/build/release: pipelines, dependency management, artifact publishing
+   
+2) System model
+   a. Summarize the primary components (runtime plus critical build/CI components when relevant).
+   b. Enumerate data flows and trust boundaries.
+      - For each trust boundary, specify:
+        * source to destination
+        * data types crossing (e.g., credentials, PII, files, tokens, prompts)
+        * channel/protocol (HTTP/gRPC/IPC/file/db)
+        * security guarantees and validation (auth, mTLS, origin checks, schema validation, rate limits)
+   c. Provide a compact Mermaid diagram showing components and trust boundaries.
+
+3) Assets and security objectives
+   - List assets (data, credentials, integrity-critical state, availability-critical components, build artifacts).
+   - For each asset, state why it matters (confidentiality/integrity/availability, compliance, user harm).
+
+4) Attacker model
+   - Capabilities: realistic remote attacker assumptions based on intended usage and exposure.
+   - Non-capabilities: things attacker cannot plausibly do (unless explicitly in scope), to avoid inflated severity.
+
+5) Threat enumeration (concrete, system-specific)
+   - Generate threats as attacker stories tied to:
+     * entry points
+     * trust boundaries
+     * privileged components
+   - Prefer abuse paths (multi-step sequences) over single-line generic threats.
+
+6) Risk prioritization
+   - For each threat:
+     * Likelihood: low/medium/high with a 1 to 2 sentence justification
+     * Impact: low/medium/high with a 1 to 2 sentence justification
+     * Overall priority: critical/high/medium/low (based on likelihood x impact, adjusted for existing controls)
+   - Explicitly state which assumptions most affect risk.
+
+7) Validate assumptions and service context with the user (required before final report)
+   - Summarize key assumptions that materially affect scope or risk ranking.
+   - Ask 1 to 3 targeted questions to resolve missing service meta-context (service owner/environment, scale/users, deployment model, authn/authz, internet exposure, data sensitivity, multi-tenancy).
+   - Pause and wait for user feedback before producing the final report.
+   - If the user cannot answer, proceed with explicit assumptions and mark any conditional conclusions.
+
+8) Mitigations and recommendations
+   - For each high/critical threat:
+     * Existing mitigations (with evidence anchors)
+     * Gaps/weaknesses
+     * Recommended mitigations (code/config/process)
+     * Detection/monitoring ideas (logging, metrics, alerts)
+
+9) Focus paths for manual security review
+   - Output 2 to 30 repo-relative paths (files or directories) that merit deeper review.
+   - For each path, give a one-sentence reason tied to the threat model.
+
+10) Quality check
+   - Provide a short checklist confirming you covered:
+     * all entry points you discovered
+     * each trust boundary at least once in threats
+     * runtime vs CI/dev separation
+     * user clarifications (or explicit non-responses)
+     * assumptions and open questions
+
+## Required output format (exact)
+Before producing the final Markdown report, first provide an assumption-validation check-in:
+- List the key assumptions in 3 to 6 bullets.
+- Ask 1 to 3 targeted context questions.
+- Wait for the user response, then produce the final report below using the clarified context.
+
+Produce valid Markdown with these sections in this order:
+
+## Executive summary
+- 1 short paragraph on the top risk themes and highest-risk areas.
+
+## Scope and assumptions
+- In-scope paths, out-of-scope items, and explicit assumptions.
+- A short list of open questions that would materially change the risk ranking.
+
+
+## System model
+### Primary components
+### Data flows and trust boundaries
+Represent the system as a sequence of arrow-style bullets (e.g., Internet → API Server, User Input -> Application Logic, etc). For each boundary, document:
+	•	the primary data types crossing the boundary,
+	•	the communication channel or protocol,
+	•	the security guarantees (e.g., authentication, origin checks, encryption, rate limiting), and
+	•	any input validation, normalization, or schema enforcement performed.
+
+#### Diagram
+- Include a single, compact Mermaid diagram (`flowchart TD` or `flowchart LR`) showing primary components and trust boundaries (e.g., separate trust zones via subgraphs). Keep it compact, use only `-->`, avoid `title`/`style`, keep node labels short (no paths/URLs), and keep edge labels to plain words only (avoid `{}`, `[]`, `()`, or quotes).
+
+
+## Assets and security objectives
+- A table: Asset | Why it matters | Security objective (C/I/A)
+
+## Attacker model
+### Capabilities
+### Non-capabilities
+
+## Entry points and attack surfaces
+- A table: Surface | How reached | Trust boundary | Notes | Evidence (repo path / symbol)
+
+## Top abuse paths
+- 5 to 10 short abuse paths, each as a numbered sequence of steps (attacker goal -> steps -> impact).
+
+## Threat model table
+- A Markdown table with columns:
+  Threat ID | Threat source | Prerequisites | Threat action | Impact | Impacted assets | Existing controls (evidence) | Gaps | Recommended mitigations | Detection ideas | Likelihood | Impact severity | Priority
+
+Rules:
+- Threat IDs must be stable and formatted: TM-001, TM-002, ...
+- Priority must be one of: critical, high, medium, low.
+- Keep prerequisites to 1 to 2 sentences. Keep recommended mitigations concrete.
+
+## Criticality calibration
+- Define what counts as critical/high/medium/low for THIS repo and context.
+- Include 2 to 3 examples per level (tailored to the repo's assets and exposure).
+
+## Focus paths for security review
+- A table: Path | Why it matters | Related Threat IDs
+
+## Notes on use
+
+- Fill in known context, but allow the model to infer and mark assumptions.
+- Include 1–2 repo-path anchors per major claim; do not dump every match.

package/dist/template/.opencode/skill/security-threat-model/references/security-controls-and-assets.md

@@ -0,0 +1,32 @@
+# Security Controls and Asset Categories
+
+Use this as a lightweight checklist to keep outputs consistent across teams. Prefer concrete, system-specific items over generic text.
+
+## Asset categories (pick only what applies)
+- User data (PII, content, uploads)
+- Authentication artifacts (passwords, tokens, sessions, cookies)
+- Authorization state (roles, policies, ACLs)
+- Secrets and keys (API keys, signing keys, encryption keys)
+- Configuration and feature flags
+- Models and weights (if ML systems)
+- Source code and build artifacts
+- Audit logs and telemetry
+- Availability-critical resources (queues, caches, rate limits, compute budgets)
+- Tenant isolation boundaries and metadata
+
+## Security control categories
+- Identity and access: authN, authZ, session handling, mTLS, key rotation
+- Input protection: schema validation, parsing hardening, upload scanning, sandboxing
+- Network safeguards: TLS, network policies, WAF, rate limiting, DoS controls
+- Data protection: encryption at rest/in transit, tokenization, redaction
+- Isolation: process sandboxing, container boundaries, tenant isolation, seccomp
+- Observability: audit logs, alerting, anomaly detection, tamper resistance
+- Supply chain: dependency pinning, SBOMs, provenance, signing
+- Change control: CI checks, deployment approvals, config guardrails
+
+## Mitigation phrasing patterns
+- "Enforce schema at <boundary> for <payload> before <component>."
+- "Require authZ check for <action> on <resource> in <service>."
+- "Isolate <parser/component> in a sandbox with <resource limits>."
+- "Rate limit <endpoint> by <key> and apply burst caps."
+- "Encrypt <data> at rest using <key management> and rotate <keys>."

package/dist/template/.opencode/skill/skill-installer/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skill-installer
+description: Use when the user asks to list, import, or install skills from OpenAI or another GitHub repository into OpenCode skill directories.
+version: 1.0.0
+tags: [workflow, automation, integration]
+dependencies: []
+---
+
+# skill-installer
+
+Import skills from GitHub into OpenCode-compatible skill directories.
+
+## When to Use
+
+- User asks to “install skill X” from `openai/skills` or another repo
+- User wants to list available curated skills before choosing
+- User wants to copy one or more external skills into local OpenCode setup
+
+## When NOT to Use
+
+- Skill already exists locally and only needs editing
+- User asked for manual adaptation (copy + rewrite), not automated install
+
+## Default Destination
+
+- Global OpenCode skill directory: `~/.config/opencode/skill`
+- Override destination with `--dest <path>`
+
+## Scripts
+
+- `scripts/list-skills.py`
+  - Lists skills from a GitHub repo path and marks already-installed skills.
+- `scripts/install-skill-from-github.py`
+  - Installs one or many skill folders from GitHub into OpenCode skill directory.
+
+## Quick Start
+
+```bash
+# List curated skills from openai/skills
+python3 .opencode/skill/skill-installer/scripts/list-skills.py
+
+# Install one curated skill into ~/.config/opencode/skill
+python3 .opencode/skill/skill-installer/scripts/install-skill-from-github.py \
+  --repo openai/skills \
+  --path skills/.curated/screenshot
+
+# Install into project-local skills directory
+python3 .opencode/skill/skill-installer/scripts/install-skill-from-github.py \
+  --repo openai/skills \
+  --path skills/.curated/gh-fix-ci \
+  --dest .opencode/skill
+```
+
+## Notes
+
+- Supports direct GitHub URLs (`--url`) and `owner/repo` (`--repo`) mode.
+- Uses authenticated API requests if `GITHUB_TOKEN` or `GH_TOKEN` is set.
+- Fails fast if destination skill directory already exists.

package/dist/template/.opencode/skill/skill-installer/scripts/github_utils.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Shared GitHub helpers for skill install scripts."""
+
+from __future__ import annotations
+
+import os
+import urllib.request
+
+
+def github_request(url: str, user_agent: str) -> bytes:
+    headers = {"User-Agent": user_agent}
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"token {token}"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req) as resp:
+        return resp.read()
+
+
+def github_api_contents_url(repo: str, path: str, ref: str) -> str:
+    return f"https://api.github.com/repos/{repo}/contents/{path}?ref={ref}"

package/dist/template/.opencode/skill/skill-installer/scripts/install-skill-from-github.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""Install a skill from a GitHub repo path into OpenCode skill directory."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import zipfile
+
+from github_utils import github_request
+
+DEFAULT_REF = "main"
+
+
+@dataclass
+class Args:
+    url: str | None = None
+    repo: str | None = None
+    path: list[str] | None = None
+    ref: str = DEFAULT_REF
+    dest: str | None = None
+    name: str | None = None
+    method: str = "auto"
+
+
+@dataclass
+class Source:
+    owner: str
+    repo: str
+    ref: str
+    paths: list[str]
+    repo_url: str | None = None
+
+
+class InstallError(Exception):
+    pass
+
+
+def _opencode_home() -> str:
+    return os.environ.get("OPENCODE_HOME", os.path.expanduser("~/.config/opencode"))
+
+
+def _tmp_root() -> str:
+    base = os.path.join(tempfile.gettempdir(), "opencode")
+    os.makedirs(base, exist_ok=True)
+    return base
+
+
+def _request(url: str) -> bytes:
+    return github_request(url, "opencode-skill-install")
+
+
+def _parse_github_url(url: str, default_ref: str) -> tuple[str, str, str, str | None]:
+    parsed = urllib.parse.urlparse(url)
+    if parsed.netloc != "github.com":
+        raise InstallError("Only GitHub URLs are supported for download mode.")
+    parts = [p for p in parsed.path.split("/") if p]
+    if len(parts) < 2:
+        raise InstallError("Invalid GitHub URL.")
+    owner, repo = parts[0], parts[1]
+    ref = default_ref
+    subpath = ""
+    if len(parts) > 2:
+        if parts[2] in ("tree", "blob"):
+            if len(parts) < 4:
+                raise InstallError("GitHub URL missing ref or path.")
+            ref = parts[3]
+            subpath = "/".join(parts[4:])
+        else:
+            subpath = "/".join(parts[2:])
+    return owner, repo, ref, subpath or None
+
+
+def _download_repo_zip(owner: str, repo: str, ref: str, dest_dir: str) -> str:
+    zip_url = f"https://codeload.github.com/{owner}/{repo}/zip/{ref}"
+    zip_path = os.path.join(dest_dir, "repo.zip")
+    try:
+        payload = _request(zip_url)
+    except urllib.error.HTTPError as exc:
+        raise InstallError(f"Download failed: HTTP {exc.code}") from exc
+    with open(zip_path, "wb") as file_handle:
+        file_handle.write(payload)
+    with zipfile.ZipFile(zip_path, "r") as zip_file:
+        _safe_extract_zip(zip_file, dest_dir)
+        top_levels = {name.split("/")[0] for name in zip_file.namelist() if name}
+    if not top_levels:
+        raise InstallError("Downloaded archive was empty.")
+    if len(top_levels) != 1:
+        raise InstallError("Unexpected archive layout.")
+    return os.path.join(dest_dir, next(iter(top_levels)))
+
+
+def _run_git(args: list[str]) -> None:
+    result = subprocess.run(
+        args, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+    )
+    if result.returncode != 0:
+        raise InstallError(result.stderr.strip() or "Git command failed.")
+
+
+def _safe_extract_zip(zip_file: zipfile.ZipFile, dest_dir: str) -> None:
+    dest_root = os.path.realpath(dest_dir)
+    for info in zip_file.infolist():
+        extracted_path = os.path.realpath(os.path.join(dest_dir, info.filename))
+        if extracted_path == dest_root or extracted_path.startswith(dest_root + os.sep):
+            continue
+        raise InstallError("Archive contains files outside the destination.")
+    zip_file.extractall(dest_dir)
+
+
+def _validate_relative_path(path: str) -> None:
+    if os.path.isabs(path) or os.path.normpath(path).startswith(".."):
+        raise InstallError("Skill path must be a relative path inside the repo.")
+
+
+def _validate_skill_name(name: str) -> None:
+    altsep = os.path.altsep
+    if not name or os.path.sep in name or (altsep and altsep in name):
+        raise InstallError("Skill name must be a single path segment.")
+    if name in (".", ".."):
+        raise InstallError("Invalid skill name.")
+
+
+def _git_sparse_checkout(
+    repo_url: str, ref: str, paths: list[str], dest_dir: str
+) -> str:
+    repo_dir = os.path.join(dest_dir, "repo")
+    clone_cmd = [
+        "git",
+        "clone",
+        "--filter=blob:none",
+        "--depth",
+        "1",
+        "--sparse",
+        "--single-branch",
+        "--branch",
+        ref,
+        repo_url,
+        repo_dir,
+    ]
+    try:
+        _run_git(clone_cmd)
+    except InstallError:
+        _run_git(
+            [
+                "git",
+                "clone",
+                "--filter=blob:none",
+                "--depth",
+                "1",
+                "--sparse",
+                "--single-branch",
+                repo_url,
+                repo_dir,
+            ]
+        )
+    _run_git(["git", "-C", repo_dir, "sparse-checkout", "set", *paths])
+    _run_git(["git", "-C", repo_dir, "checkout", ref])
+    return repo_dir
+
+
+def _validate_skill(path: str) -> None:
+    if not os.path.isdir(path):
+        raise InstallError(f"Skill path not found: {path}")
+    skill_md = os.path.join(path, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        raise InstallError("SKILL.md not found in selected skill directory.")
+
+
+def _copy_skill(src: str, dest_dir: str) -> None:
+    os.makedirs(os.path.dirname(dest_dir), exist_ok=True)
+    if os.path.exists(dest_dir):
+        raise InstallError(f"Destination already exists: {dest_dir}")
+    shutil.copytree(src, dest_dir)
+
+
+def _build_repo_url(owner: str, repo: str) -> str:
+    return f"https://github.com/{owner}/{repo}.git"
+
+
+def _build_repo_ssh(owner: str, repo: str) -> str:
+    return f"git@github.com:{owner}/{repo}.git"
+
+
+def _prepare_repo(source: Source, method: str, tmp_dir: str) -> str:
+    if method in ("download", "auto"):
+        try:
+            return _download_repo_zip(source.owner, source.repo, source.ref, tmp_dir)
+        except InstallError as exc:
+            if method == "download":
+                raise
+            err_msg = str(exc)
+            if "HTTP 401" in err_msg or "HTTP 403" in err_msg or "HTTP 404" in err_msg:
+                pass
+            else:
+                raise
+    if method in ("git", "auto"):
+        repo_url = source.repo_url or _build_repo_url(source.owner, source.repo)
+        try:
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+        except InstallError:
+            repo_url = _build_repo_ssh(source.owner, source.repo)
+            return _git_sparse_checkout(repo_url, source.ref, source.paths, tmp_dir)
+    raise InstallError("Unsupported method.")
+
+
+def _resolve_source(args: Args) -> Source:
+    if args.url:
+        owner, repo, ref, url_path = _parse_github_url(args.url, args.ref)
+        if args.path is not None:
+            paths = list(args.path)
+        elif url_path:
+            paths = [url_path]
+        else:
+            paths = []
+        if not paths:
+            raise InstallError("Missing --path for GitHub URL.")
+        return Source(owner=owner, repo=repo, ref=ref, paths=paths)
+
+    if not args.repo:
+        raise InstallError("Provide --repo or --url.")
+    if "://" in args.repo:
+        return _resolve_source(
+            Args(url=args.repo, repo=None, path=args.path, ref=args.ref)
+        )
+
+    repo_parts = [p for p in args.repo.split("/") if p]
+    if len(repo_parts) != 2:
+        raise InstallError("--repo must be in owner/repo format.")
+    if not args.path:
+        raise InstallError("Missing --path for --repo.")
+    paths = list(args.path)
+    return Source(
+        owner=repo_parts[0],
+        repo=repo_parts[1],
+        ref=args.ref,
+        paths=paths,
+    )
+
+
+def _default_dest() -> str:
+    return os.path.join(_opencode_home(), "skill")
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = argparse.ArgumentParser(description="Install a skill from GitHub.")
+    parser.add_argument("--repo", help="owner/repo")
+    parser.add_argument("--url", help="https://github.com/owner/repo[/tree/ref/path]")
+    parser.add_argument(
+        "--path",
+        nargs="+",
+        help="Path(s) to skill(s) inside repo",
+    )
+    parser.add_argument("--ref", default=DEFAULT_REF)
+    parser.add_argument("--dest", help="Destination skills directory")
+    parser.add_argument(
+        "--name", help="Destination skill name (defaults to basename of path)"
+    )
+    parser.add_argument(
+        "--method",
+        choices=["auto", "download", "git"],
+        default="auto",
+    )
+    return parser.parse_args(argv, namespace=Args())
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+    try:
+        source = _resolve_source(args)
+        source.ref = source.ref or args.ref
+        if not source.paths:
+            raise InstallError("No skill paths provided.")
+        for path in source.paths:
+            _validate_relative_path(path)
+        dest_root = args.dest or _default_dest()
+        tmp_dir = tempfile.mkdtemp(prefix="skill-install-", dir=_tmp_root())
+        try:
+            repo_root = _prepare_repo(source, args.method, tmp_dir)
+            installed = []
+            for path in source.paths:
+                skill_name = args.name if len(source.paths) == 1 else None
+                skill_name = skill_name or os.path.basename(path.rstrip("/"))
+                _validate_skill_name(skill_name)
+                if not skill_name:
+                    raise InstallError("Unable to derive skill name.")
+                dest_dir = os.path.join(dest_root, skill_name)
+                if os.path.exists(dest_dir):
+                    raise InstallError(f"Destination already exists: {dest_dir}")
+                skill_src = os.path.join(repo_root, path)
+                _validate_skill(skill_src)
+                _copy_skill(skill_src, dest_dir)
+                installed.append((skill_name, dest_dir))
+        finally:
+            if os.path.isdir(tmp_dir):
+                shutil.rmtree(tmp_dir, ignore_errors=True)
+        for skill_name, dest_dir in installed:
+            print(f"Installed {skill_name} to {dest_dir}")
+        return 0
+    except InstallError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))