skillx run

Synopsis

skillx run <source> [prompt] [options]

skillx run is the fastest way to go from “I found a skill” to “the agent is using it right now”. Use it for first-run testing, one-off tasks, and validating a skill before you decide whether it belongs in your regular project workflow.

Behind one command, skillx resolves the source, scans it, injects it into the current agent, launches the session, then cleans everything up when the run ends. The usual progression is: start with run, switch to scan when you want a clearer security decision, then move to project-level management once the skill proves useful.

Arguments

Argument	Required	Description
`source`	No	Skill source: local path, `github:`/`gist:` prefix, or platform URL. Required if no `skillx.toml` exists.
`prompt`	No	Prompt text to pass to the agent

Options

Flag	Short	Default	Description
`--file <path>`	`-f`	—	Read the prompt from a file
`--stdin`	—	—	Read the prompt from stdin
`--agent <name>`	—	auto-detect	Target agent (skip auto-detection)
`--scope <scope>`	—	`global`	Injection scope: `global` or `project`
`--attach <path>`	—	—	Attach files for the agent (repeatable)
`--no-cache`	—	—	Force re-fetch, skip cache
`--skip-scan`	—	—	Skip the security scan (not recommended)
`--yes`	—	—	Auto-confirm WARN level risks
`--auto-approve`	`--auto`	—	Pass permission-skip flags to the agent
`--headless`	—	—	Run without interactive terminal UI when the selected agent supports it
`--fail-on <level>`	—	`danger`	Stop before launch if scan results meet or exceed `info`, `warn`, `danger`, or `block`
`--print`	`-p`	—	Non-interactive mode: agent processes prompt and exits
`--timeout <dur>`	—	—	Maximum run duration (e.g., `30m`, `2h`)

Lifecycle Phases

Phase 1: Resolve

The source string is resolved in this priority order:

Local path — starts with ./, /, ~/, or exists on disk
github: prefix — e.g., github:owner/repo/path[@ref]
gist: prefix — e.g., gist:abc123[@revision]
Platform URL — GitHub, GitLab, Bitbucket, Gitea/Codeberg, SourceHut, HuggingFace URLs
Archive URL — direct .zip or .tar.gz download links

skillx may also accept other compatible source URLs, including selected legacy directory links that resolve to underlying Git repositories. Those compatibility paths exist for existing links, not as the primary discovery workflow.

If no source is provided and a skillx.toml exists with [skills] entries, all listed skills are run sequentially.

Remote skills are cached after download. Use --no-cache to force a fresh fetch.

Phase 2: Scan

Unless --skip-scan is set, the skill is scanned by the built-in security engine. The scan report is printed to stderr.

Phase 3: Gate

The overall risk level determines how the run proceeds:

Level	Behavior
PASS / INFO	Auto-continue
WARN	Prompt `Continue? [Y/n]` (skipped with `--yes`)
DANGER	Require typing `yes`; supports `detail N` to inspect findings
BLOCK	Execution refused, exit code 1

Phase 4: Detect Agent

If --agent is not specified, skillx auto-detects installed agents. If multiple are found, an interactive selector is shown.

Available agents: claude-code, codex, copilot, cursor, gemini-cli, opencode, amp, windsurf, cline, roo, and 21 more generic agents. Run skillx agents --all for the full list.

Phase 5: Inject

Skill files are copied to the agent’s expected directory:

Agent	Global Scope	Project Scope
Claude Code	`~/.claude/skills/<name>/`	`.claude/skills/<name>/`
Codex	`~/.codex/skills/<name>/`	`.agents/skills/<name>/`
Gemini CLI	`~/.gemini/skills/<name>/`	`.gemini/skills/<name>/`
OpenCode	`~/.opencode/skills/<name>/`	`.opencode/skills/<name>/`
Amp	`~/.config/agents/skills/<name>/`	`.agents/skills/<name>/`
Copilot	`~/.github/skills/<name>/`	`.github/skills/<name>/`
Cursor	`~/.cursor/skills/<name>/`	`.cursor/skills/<name>/`
Windsurf	`~/.windsurf/skills/<name>/`	`.windsurf/skills/<name>/`
Cline	`~/.cline/skills/<name>/`	`.cline/skills/<name>/`
Roo Code	`~/.roo/skills/<name>/`	`.roo/skills/<name>/`
Universal	`~/.agents/skills/<name>/`	`.agents/skills/<name>/`

Each file is hashed with SHA-256 and recorded in the session manifest.

Phase 6: Launch

CLI agents (Claude Code, Codex, Gemini CLI, OpenCode, Amp, and Tier 3 CLI agents): spawned as child processes with the prompt as an argument
IDE agents (Copilot, Cursor, Windsurf, Cline, Roo Code, Universal, and Tier 3 IDE agents): prompt copied to clipboard; skillx waits for Enter

When --print is used, CLI agents are launched in non-interactive mode: the agent processes the prompt and exits automatically without opening an interactive session. The exact flag varies by agent (e.g., claude -p, codex exec, gemini -p, opencode run).

Phase 7: Wait

skillx waits for the agent to finish. Supports:

Ctrl+C — kills the agent process and triggers cleanup
--timeout — kills the agent after the specified duration

Phase 8: Clean

All injected files are removed, the session manifest is archived to ~/.skillx/history/, and orphaned sessions from previous interrupted runs are recovered.

Prompt Sources

Prompts are resolved in priority order:

CLI argument: skillx run ./skill "Do the thing"
File: skillx run ./skill -f prompt.txt
Stdin: echo "Do the thing" | skillx run ./skill --stdin
None: Agent launches without an initial prompt

Examples

Basic usage

skillx run github:skillx-run/skillx/examples/skills/hello-world "Hello"

GitHub skill with timeout

skillx run --timeout 30m github:skillx-run/skillx/examples/skills/code-review "Review the auth module"

Pipe prompt from another command

git diff HEAD~1 | skillx run github:skillx-run/skillx/examples/skills/code-review --stdin

Project-scoped injection

skillx run --scope project github:skillx-run/skillx/examples/skills/hello-world "Set up the project"

Non-interactive (print) mode

skillx run --print github:skillx-run/skillx/examples/skills/code-review "Review src/main.rs"

Auto-approve mode with auto-confirm

skillx run --yes --auto-approve github:skillx-run/skillx/examples/skills/code-review "Fix all lint errors"

Attach context files

skillx run github:skillx-run/skillx/examples/skills/code-review \
  --attach ./data.csv \
  --attach ./schema.sql \
  "Review the data processing code"

If you are inside a local clone of the repository and want to point at the checked-out example files directly, swap the GitHub source for ./examples/skills/<name>.

Exit Codes

Code	Meaning
0	Success
1	Error (scan blocked, agent failure, source resolution failed)

After `run` starts working

Once a one-off run is useful, the next step is usually to stabilize how you use it:

Scan Skills when you want to review the same security gate without launching an agent
Manage Project Skills when the skill should graduate from ad hoc runs to skillx.toml-based project usage
Agent System Overview when you need to understand agent-specific injection paths and launch behavior
FAQ when you are still deciding between one-off, scanned, and persistent workflows
Troubleshooting when the failure is still basic first-run setup, source resolution, or agent detection