Skip to content

getting-started.md

Latest commit

 

History

History
195 lines (139 loc) · 6.26 KB

getting-started.md

File metadata and controls

195 lines (139 loc) · 6.26 KB
Raw

Getting Started

This guide takes a new user from installation to a verified live SkillRun. Skill Runtime observes supported Agents beside their normal workflow; it does not proxy model requests, replace the Agent UI, or require a cloud account.

Requirements

  • macOS or Linux;
  • Python 3.9 or newer;
  • at least one supported Agent: Codex, Claude Code, Qoder, or OpenCode;
  • a browser for the local UI.

The standalone installer does not require sudo, a GitHub account, GitHub CLI, or a source checkout.

1. Install and start

curl -LsSf https://raw.githubusercontent.com/hellogxp/skill-runtime-intelligence/main/scripts/install.sh | sh -s -- --start

The installer:

  1. downloads the release payload for the current platform;
  2. verifies the published SHA-256 checksum;
  3. detects supported Agents and scans standard Skill locations;
  4. shows every path it intends to read or manage;
  5. asks once before enabling observation-only, fail-open integrations;
  6. creates ~/.skill-runtime/config.json and ~/.skill-runtime/data/panorama.db;
  7. starts the local Collector and UI.

All stored runtime evidence stays under ~/.skill-runtime by default.

2. Connect your Agent

Accepting Hook setup during installation enables every detected integration. To inspect the plan without changing any Agent configuration:

skill-runtime setup

To enable only one integration later:

skill-runtime setup --enable-codex-hooks
skill-runtime setup --enable-claude-hooks
skill-runtime setup --enable-qoder-hooks
skill-runtime setup --enable-opencode-plugin

Every managed configuration entry has a Skill Runtime marker. Existing entries are preserved and a backup is created before a supported configuration file is changed.

Codex

  1. Run skill-runtime setup --enable-codex-hooks.
  2. Open /hooks in Codex.
  3. Review and trust the commands managed by Skill Runtime.
  4. Start a new Codex task; already-open tasks do not hot-load new Hooks.

Claude Code

Enable the managed Hooks, restart Claude Code if it was already running, and begin a new session.

Qoder

Enable the managed Hooks and restart Qoder. Qoder loads its Hook configuration at process startup.

OpenCode

Enable the managed observation-only plugin and restart OpenCode if its current process predates installation.

3. Produce and verify live evidence

Use a Skill normally in a new Agent task. Then run:

skill-runtime doctor

The integration states have strict meanings:

State Meaning
Live / Verified The local database received a real runtime event from this integration
Pending Configuration exists, but no real event has arrived yet
Fallback Evidence is being reconstructed from compatible local records
Unsupported This Agent/version does not expose the relevant signal
Disabled The integration was not enabled

Writing a Hook configuration is never enough to claim live collection.

Open http://127.0.0.1:4317. The Runtime Overview identifies runs worth investigating; selecting a run opens its ordered Panorama, first observable boundary, evidence timeline, and Inspector.

4. Understand what is real

Every node and relationship carries an evidence grade:

  • Observed — directly present in a source event or scanned file;
  • Derived — deterministically connected from observed evidence;
  • Inferred — an uncertain explanation that cannot rewrite facts;
  • Experimental — an effect measured through controlled evaluation.

Not observed is not a synonym for failed. The adapter capability panel shows whether a source could have emitted the missing signal.

5. Runtime lifecycle

skill-runtime status
skill-runtime doctor
skill-runtime restart
skill-runtime stop
skill-runtime uninstall --keep-data

uninstall removes only entries and files owned by Skill Runtime. Without --keep-data, deletion of ~/.skill-runtime requires explicit confirmation. Agent sessions, projects, and Skill sources are never removed.

6. Privacy and network behavior

  • The server binds to 127.0.0.1 by default.
  • Prompts, raw tool payloads, patch bodies, credentials, and Skill resource contents are not copied into the normalized index.
  • Common secret patterns are redacted before persistence.
  • Network export is off until an endpoint is explicitly configured.
  • Hook delivery is bounded and fail-open: a collection failure does not deny, modify, or delay an Agent decision beyond the small configured timeout.

Review the exact data boundaries in Architecture and the signal limitations in the adapter capability matrix.

7. Connect an observability platform

Skill Runtime exports normalized Skill-specific evidence over OTLP/HTTP:

skill-runtime start \
  --otlp-endpoint https://collector.example/v1/traces

For authenticated background export, use the standard OTEL_EXPORTER_OTLP_HEADERS environment variable before starting the runtime. Secrets are not written into Skill Runtime configuration or command history by the product.

See Observability platform setup for Grafana/OpenTelemetry Collector, Datadog, and other OTLP-compatible backends, plus supported historical import profiles.

Troubleshooting

The integration stays Pending

  • confirm the Agent was restarted after setup;
  • create a new task/session rather than reusing an existing one;
  • for Codex, confirm the managed commands are trusted in /hooks;
  • use a Skill so the Agent actually emits a Skill-relevant event;
  • run skill-runtime status, then skill-runtime doctor.

The UI shows Transcript fallback

No verified primary event has arrived for that run. The transcript adapter is serving compatibility evidence and the UI labels it accordingly. Check skill-runtime doctor and the adapter capability matrix.

Port 4317 is already in use

skill-runtime stop
skill-runtime start --port 4318

Then open http://127.0.0.1:4318.

I do not want Hooks

skill-runtime install --no-hooks

The product remains usable for Skill inventory, supported imports, and labeled fallback reconstruction, but it will not present those records as primary live Hook evidence.