Metadata-Version: 2.5
Name: skillctl-secure
Version: 0.30.9
Summary: Package manager, trust layer, and portability layer for Agent Skills
Project-URL: Homepage, https://github.com/brian-scardina/skillctl
Project-URL: Repository, https://github.com/brian-scardina/skillctl
Project-URL: Documentation, https://github.com/brian-scardina/skillctl/tree/main/docs
Project-URL: Issues, https://github.com/brian-scardina/skillctl/issues
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: packaging>=24.0
Requires-Dist: pyyaml<7,>=6
Requires-Dist: rich>=13
Requires-Dist: textual>=1.0
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pyinstaller<7,>=6; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.23; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.4; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# skillctl

**Package manager, trust layer, and portability layer for AI Agent Skills.**

skillctl discovers, audits, installs, updates, pins, inventories, and exposes Agent
Skills to compatible AI hosts while preserving publisher provenance and local policy.

```bash
skillctl
```

> Python distribution: `skillctl-secure`. Product name, import package, and console
> command remain `skillctl`.

## Quick start

### Complete setup in one command

For a new machine, use the [complete bootstrap instructions](docs/BOOTSTRAP.md).
The standalone macOS/Linux and Windows scripts install missing Git, uv, and Python,
install or update skillctl, configure PATH, verify the command, and launch the app.
OS-required dialogs or sudo prompts may still require interaction.

### Recommended: install with uv

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) once, then:

```bash
uv tool install --python 3.12 skillctl-secure
skillctl
```

Works on macOS, Linux, and Windows. uv automatically downloads Python when needed
and installs skillctl in an isolated environment. No Apple developer membership,
Windows signing subscription, administrator access, or source checkout is required.

If you have the convenience installer from this repository or a release, it handles
uv setup and installs the same Python package:

```bash
sh ./install.sh                 # macOS / Linux
```

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

The PowerShell policy override applies only to this installer process. Managed
organization policies may still restrict installation.

Update or remove the application:

```bash
uv tool upgrade skillctl-secure
uv tool uninstall skillctl-secure
```

Uninstalling the application leaves your skills and state intact. `pipx install
skillctl-secure` is also supported if you already use pipx.

### Install automatically and launch

Download `skillctl.sh` (macOS/Linux) or `skillctl.ps1` (Windows). Each launcher is
self-contained and can live outside the repository. On first use it installs uv,
Python, and skillctl as needed, then starts the application. Later runs start the
installed version without checking for updates or requiring an internet connection.

```bash
sh ./skillctl.sh
sh ./skillctl.sh --version
```

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\skillctl.ps1
```

Arguments are passed to skillctl. Run `uv tool upgrade skillctl-secure` when you want
to update. The launcher uses uv's tool directory, so it also works before opening a
new terminal to refresh PATH. `install.sh` and `install.ps1` remain install/update-only.

### Optional standalone executables

Self-contained native executables remain an optional release channel, enabled by
maintainers only after native signing is provisioned. Python releases do not depend
on Apple or Windows credentials. GitHub release files include SHA-256 checksums and
keyless Sigstore signatures; see [release verification](docs/VERIFY-RELEASE.md).

For contributors:

```bash
uv sync --extra dev
uv run skillctl
```

See [`docs/FIRST-RUN.md`](docs/FIRST-RUN.md) for the safe first-use walkthrough and
[`docs/PORTABLE-INSTALL.md`](docs/PORTABLE-INSTALL.md) for the distribution/release model.
Release authors should use [`docs/RELEASE-NOTES-TEMPLATE.md`](docs/RELEASE-NOTES-TEMPLATE.md).

## Supported hosts

| Host | Agent Skills format | skillctl |
|---|---|---|
| GitHub Copilot | Native | Native personal path via `~/.agents/skills` |
| OpenAI Codex | Native/compatible | Native |
| Claude Code | Agent Skills-compatible | Portable/partial depending on skill tools |
| Microsoft 365 Copilot | Different agent model | Export adapter available; review required before import |

```bash
skillctl hosts
skillctl compatibility <skill>
```

Format compatibility and skill runtime compatibility are intentionally separate.

## Architecture and host compatibility

skillctl deliberately separates skill lifecycle/trust from the AI host that executes
the skill. The default runtime target is `~/.agents/skills`, a vendor-neutral Agent
Skills location that is also supported by GitHub Copilot.

- [Architecture](docs/ARCHITECTURE.md)
- [Portable installation](docs/PORTABLE-INSTALL.md)
- [First run](docs/FIRST-RUN.md)
- [Host compatibility](docs/HOST-COMPATIBILITY.md)
- [Release notes template](docs/RELEASE-NOTES-TEMPLATE.md)

## Trust states

- **VERIFIED** — explicitly trusted source/publisher.
- **AUDITED** — skillctl audit completed.
- **REVIEWED** — user explicitly reviewed and overrode HIGH findings.
- **UNVERIFIED** — no trust/audit evidence yet.
- **MODIFIED** — installed contents no longer match the install-time digest.

## Skill Inspector

```bash
skillctl inspect archify
```

The TUI inspector shows provenance, versions, license, trust, integrity, dependencies,
dependents, audit results, and observed capabilities.

## Dependency management

```bash
skillctl dependency-plan biso-security-review
skillctl install biso-security-review
```

Installation automatically installs missing dependencies. Uninstalling a dependency
required by another installed skill is blocked unless `--force` is explicitly used.

## Profiles

```bash
skillctl profile-save Security --description "Security review toolbox"
skillctl profile-apply Security
skillctl profile-apply Security --prune
```

Default profile application is additive. `--prune` makes it a true switch.

## Reproducible toolbox export

```bash
skillctl toolbox-export ~/skillctl-toolbox.yaml
skillctl toolbox-restore ~/skillctl-toolbox.yaml
```

Git-backed skills restore at the recorded installed commit when possible.

## Collections

```bash
skillctl collections
skillctl collection-install starter
skillctl collection-install architecture
skillctl collection-install security-workbench
```

## Workbenches

```bash
skillctl workbenches
```

Security Review remains an optional workbench built on top of the skill package manager.

## Policy

Policy is enforced during installation and lives at `~/.skillctl/policy.yaml`.

```bash
skillctl policy
skillctl policy archify
```

Use the **Policy** tab/button in the TUI (`P`) to inspect rules and a selected
skill's ALLOW / REVIEW / DENY decision. Existing corrupt policy files fail closed;
an explicit policy DENY cannot be overridden by `--force`.

## Doctor

```bash
skillctl doctor
```

Doctor checks runtime tools, manifest health, installed-skill integrity,
dependency graphs, audit freshness/errors, profiles, and collections. It is
also available directly from the **Doctor** tab/button (`D`) in the TUI.

## Safe updates and lockfile

Use `skillctl update-review <skill>` or the TUI update flow to compare the exact
proposed commit. `skillctl lock`, `lock-status`, and `lock-restore` manage
`skillctl.lock`; use the Toolbox TUI view (`L`) for the same health information.

For reviewed environment changes, generate a reconciliation artifact before applying it:

```bash
skillctl reconcile-plan default --desired <skill-name> --output reviewed-plan.json
skillctl reconcile-apply reviewed-plan.json --ack-review
```

Tampered, stale, preview-only, or source-drifted review artifacts are refused.

## Declared permissions

Skills may declare `permissions:` in SKILL.md frontmatter. skillctl compares the
declaration with observed capabilities and reports MATCH / DRIFT / UNDECLARED.
Use the Permissions TUI view (`M`) or `skillctl permissions <skill>`.

## Catalog & publishers

```bash
skillctl catalog
skillctl catalog security
skillctl publishers
skillctl publisher-trust tt-a1i
```

The TUI Available view shows publisher/category metadata and search includes
publisher and tags. The **Publishers** view (`T`) shows local trust state.

Publisher trust is intentionally a local governance signal, not a claim of
cryptographic publisher identity. Signed provenance is a later milestone.

## Isolated environments

The `default` environment preserves the existing configured install path. New
environments receive separate install/state/lock roots:

```text
~/.skillctl/environments/Security/
  skills/
  state.json
  skillctl.lock
```

Use the **Environments** TUI view (`E`) and **New Env** (`N`), or:

```bash
skillctl environments
skillctl environment-create Security --description "Security review toolbox"
skillctl environment-use Security
skillctl environment-apply Security
```

Activation changes skillctl's active management context. Runtime binding is an explicit,
reversible operation; skillctl does not replace an external runtime directory implicitly.

## Environment lifecycle

The TUI Environments view supports:

- **Activate** — switch skillctl's management context.
- **Clone Current** — copy installed skills, state/provenance, and lockfile.
- **Rename** — rename an isolated environment.
- **Delete** — delete an inactive environment definition.
- **Bind Runtime** — explicitly expose an isolated environment to the external agent runtime.
- **Unbind Runtime** — restore the pre-binding runtime path.

CLI equivalents and additional operational details are documented in the environment and reconciliation guides.

## Recovery and upgrades

Reconciliation uses durable transaction metadata so process interruption can be recovered
or refused safely before another mutation. Do not delete authoritative state to bypass a
recovery or schema error.

- [Recovery and troubleshooting](docs/RECOVERY.md)
- [Environment reconciliation](docs/RECONCILIATION.md)
- [Upgrade and persisted-format guidance](docs/UPGRADES.md)
- [CLI/API contract](docs/CLI-CONTRACT.md)

### Choose where a skill is installed

In the TUI, select a skill and choose **Install…**, including when the skill
is already installed in the active toolbox. Select one or more destinations,
choose **Review selection**, inspect the source findings and runtime requirements,
and choose **Apply selected**. **Update** and **Uninstall** also let you select
which destinations to change. **Update all** applies only to the active toolbox.

The header identifies the current **Toolbox**, which is an isolated skillctl skill
set. It is separate from an AI app destination. Skill details show the destination
paths and local status. **Installed locally** means validated files exist; it does
not establish that an AI session has discovered or executed them. Detection of an
app/configuration is also separate from discovery of a skill inside the app.

The selector offers personal destinations for Codex, GitHub Copilot, and Claude
Code. Use **Add destination** for a project or another local installation, specifying
the app and its actual skill directory. For example, use `/repo/.github/skills`
for a GitHub Copilot project. Shared directories are written once; removing a
shared copy can affect every app reading that directory. Unmanaged or locally
modified files are protected from replacement and removal.

**Microsoft 365 Copilot Cowork** is a separate destination from GitHub Copilot and
ordinary Copilot Chat. The installer prepares ZIP packages with `SKILL.md` at the
archive root. In Cowork, use **Customize → Skills → Add → Upload skill**, including
packages for required dependencies. Status remains **Import required**; local
packaging does not confirm import or runtime compatibility. Test in a new
conversation. Removing the local export does not remove the imported Cowork skill.
See [Microsoft's Cowork import documentation](https://learn.microsoft.com/en-us/microsoft-365/copilot/cowork/cowork-customize).

CLI equivalents:

```bash
skillctl destinations archify
skillctl install-to archify --target codex --target github-copilot
skillctl install-to archify --target codex --target github-copilot --apply
skillctl install-to archify --target github-copilot --operation update --apply
skillctl install-to archify --target github-copilot --operation remove --apply
```

Without `--apply`, `install-to` only reviews the selected destinations. REVIEW
items additionally require `--approve-review`; DENY items remain blocked.
Operations complete independently by destination, so inspect each result when
some destinations fail. Existing `install` and collection commands continue to
use the active toolbox.

### Discover skills already on this computer

Startup and **Ctrl+R** scan known local skill directories automatically. Open
**Skills → Inventory** (or the inventory row on Home) to see skills installed by
skillctl, another installer, or manual copying—even when they are absent from the
source catalog. **Installed here** remains scoped to the active toolbox.

Inventory shows each physical copy's app destinations, paths, description,
version when available, and ownership. Shared directories and linked aliases are
grouped; independent copies remain separate. Invalid metadata, unreadable roots,
and missing files with an installation record are reported. Audit-only catalog
records do not count as installed skills.

Discovery reads bounded `SKILL.md` metadata from supported personal directories,
Codex's system-skill directory, the launch directory's standard project skill
folders, registered project destinations, and named toolboxes. It does not walk
the entire disk, infer installed plugins from cached versions, execute skill
instructions, or take ownership of external files. Cloud/account imports and
actual discovery inside an AI session remain unverified.

Use `skillctl inventory` or `skillctl inventory --json` for the same discovery from
the command line. JSON output also includes scan time, checked roots, and errors.

### Audit an existing installed copy

In **Skills → Inventory**, select a copy and choose **View audit findings** (or
press `a`). Run **Audit** to inspect local instructions and scripts, including
skills skillctl does not manage. Findings show locations, risks, and suggested
fixes. Auditing does not adopt the skill, modify its files, or execute it.

Enable **Check CVEs online** to query [OSV](https://osv.dev/) for known dependency
vulnerabilities, including CVE aliases, advisory severity, and fixed versions when
available. This sends dependency names, ecosystems, and exact versions to OSV;
it does not send skill contents. Online checks are off by default.

```sh
skillctl audit-path /path/to/installed/skill
skillctl audit-path /path/to/installed/skill --cves --json
```

Dependency coverage includes exact pins in `requirements.txt`, public PyPI entries
in `uv.lock` and `poetry.lock`, `Pipfile.lock`, and npm `package-lock.json` (including
locked transitive dependencies). Requirements ranges, other manifests, bundled
libraries, and dependencies downloaded at runtime need separate review. Package
advisory matches do not establish exploitability in this skill.

Reports identify skipped files and incomplete lookups. Each audit uses a temporary
snapshot capped at 2,000 files/directories, 2 MB per file, and 20 MB total; linked files, special
files, `.git`, `node_modules`, `.venv`, and `__pycache__` are skipped. Online checks
are bounded to 100 dependency versions and 50 advisory details. Reports are shown
for the current audit; use `--json` to save them. Re-audit after changes. With
`--cves`, exit status 2 indicates missing or incomplete online checks; advisory
presence is reported in the result, not the exit status.

### Installed-skills attack surface and risk

Open the top-level **Attack Surface & Risk** tab beside **Skills** for an interactive tree of AI
app destinations, local skill copies, and observed indicators such as credential
references, code execution, network references, and instruction overrides. Select
any copy or indicator for its source locations, findings, risks, and suggested
fixes. A shared physical copy appears under each destination but counts once;
separate copies with the same name remain distinct. Export-only packages are
shown but excluded from the installed-copy rating.

Choose **Assess installed skills** to take fresh, read-only audits of up to 100
copies. Enable the CVE checkbox to include OSV checks. The map initially shows
**UNKNOWN** because discovery alone is not an audit. The assessment remains available when switching tabs. Opening the page performs
metadata discovery; choose **Assess installed skills** to refresh findings.
Restarting the app starts a new assessment.

The overall **installed-skill risk** uses the highest observed heuristic severity.
An affected dependency advisory imposes a **MEDIUM** review floor; this is a
triage rule, not a calculated CVSS rating. Ratings are provisional when copies
are unaudited, files are skipped, discovery fails, or CVE coverage is incomplete.
Incomplete coverage with no findings is **UNKNOWN**, never a clean bill of health.
This is a map of discovered local skills and static indicators, not a verified
attack graph, evidence of app loading, or an overall operating-system assessment.

```sh
skillctl attack-surface                   # discovery map; no audits or network
skillctl attack-surface --audit           # fresh offline assessment
skillctl attack-surface --cves --json     # assessment with OSV; machine-readable report
```
