Skip to content

skill-installation-and-distribution.md

Latest commit

 

History

History
144 lines (95 loc) · 5.4 KB

skill-installation-and-distribution.md

File metadata and controls

144 lines (95 loc) · 5.4 KB
Raw

Quantex Skill Installation And Distribution

This document explains how the repo-local Quantex CLI skill is installed, validated, updated, and shared today.

Scope

The Quantex CLI skill is a repo-native skill for Codex and similar agents that should operate Quantex through its lifecycle CLI surface instead of calling downstream agent binaries ad hoc.

This document is about the user-facing skills/quantex-cli/ skill. The separate skills/quantex-agent-runtime/ directory is contributor-facing repository workflow runtime for agents developing this repo; it is not part of the normal external user installation path.

This document covers:

  • where the skill lives in this repository
  • how to point an agent runtime at it
  • how to validate changes safely
  • what "distribution" means today

This document does not define a marketplace or packaged publishing flow because that does not exist yet.

Skill layout

The canonical user-facing skill files live under skills/quantex-cli/:

  • SKILL.md: the main operating instructions for agents
  • agents/openai.yaml: agent-specific metadata
  • references/: supporting command, automation, output, and troubleshooting references
  • assets/: icons and visual assets
  • scripts/smoke-check.sh: lightweight validation for the Quantex command surface

When the Quantex CLI behavior changes, update the relevant canonical project-memory artifact first:

  • behavior contract: openspec/
  • durable decision: docs/adr/
  • troubleshooting or recovery knowledge: docs/runbooks/

Then update the skill files so they reflect the same contract.

If a skill reference keeps a maintained supported-agent snapshot, verify it against bun run dev -- list --json and the current src/agents/catalog/*.json set in the same branch.

The contributor-facing runtime lives separately under skills/quantex-agent-runtime/. Use it when working inside this repository with Superpowers, OpenSpec intake, validation, and delivery closure rules. Do not document it as the default skill for users who only want to operate Quantex.

Installation model

Today the Quantex CLI skill is installed from the repository itself. There is no separate npm package, marketplace release, or standalone bundle.

Use one of these patterns:

  1. Install from GitHub with the skills CLI:

    npx skills add Drswith/quantex-cli --skill quantex-cli

  2. Work directly from this repository when the agent runtime can read repo-local skills.

  3. Copy or sync skills/quantex-cli/ into the target skill directory if the runtime expects installed skills outside the repository.

The important requirement is that the runtime sees the whole skills/quantex-cli/ directory, not only SKILL.md, because the references, metadata, assets, and smoke-check script are part of the maintained artifact.

To inspect the available skills before installing, run:

npx skills add Drswith/quantex-cli --list

Validation

When maintaining the CLI surface or the skill itself, run:

skills/quantex-cli/scripts/smoke-check.sh

The script resolves quantex in this order:

  1. QUANTEX_BIN if explicitly provided
  2. bun run src/cli.ts from this repository when bun is available
  3. a globally available quantex binary in PATH

Useful examples:

# Use the repo checkout with Bun
skills/quantex-cli/scripts/smoke-check.sh

# Validate against a specific built binary
QUANTEX_BIN=./dist/bin/quantex skills/quantex-cli/scripts/smoke-check.sh

# Change the smoke agent when needed
QUANTEX_SMOKE_AGENT=claude skills/quantex-cli/scripts/smoke-check.sh

The smoke check currently verifies:

  • capabilities --json
  • commands --json
  • schema --json
  • schema inspect --json
  • inspect <agent> --json
  • resolve <agent> --json when that agent is already installed

Run this after updating:

  • command names or flags
  • JSON envelope or schema behavior
  • lifecycle command expectations in the skill
  • skill references that describe structured usage
  • skill references that enumerate supported agent names

Update flow

Use this update order:

  1. Change the Quantex CLI behavior or project-memory artifact first.
  2. Update skills/quantex-cli/ so the skill matches the current contract.
  3. Run skills/quantex-cli/scripts/smoke-check.sh.
  4. If the change affects durable docs, update the linked runbook, ADR, or OpenSpec artifact in the same branch.

Treat skills/quantex-cli/ as a consumer-facing integration layer, not the source of truth for product behavior. Treat skills/quantex-agent-runtime/ as repository workflow runtime for contributors.

Distribution today

Supported today:

  • sharing the repository itself
  • pinning to a repository revision or branch
  • installing from GitHub through npx skills add Drswith/quantex-cli --skill quantex-cli
  • copying the repo-local skill directory into another compatible skill location

Not supported today:

  • a dedicated skill package
  • a public skill marketplace flow
  • an automated release pipeline that publishes the skill independently from this repository

So in practice, the user-facing Quantex CLI skill is currently distributed as part of the repository, alongside the CLI and its project-memory artifacts.

Related files

  • skills/quantex-cli/SKILL.md
  • skills/quantex-agent-runtime/SKILL.md
  • skills/quantex-cli/scripts/smoke-check.sh
  • skills/quantex-cli/references/command-recipes.md
  • skills/quantex-cli/references/output-contracts.md
  • docs/runbooks/quantex-troubleshooting.md