Metadata-Version: 2.4
Name: steer-ai
Version: 0.1.0
Summary: The framework for building Agent Skills: scaffolding, validation, packaging, and runtime components (secrets, storage, context, flows, processes, learning) for SKILL.md
Project-URL: Homepage, https://github.com/bh-rat/steer
Project-URL: Documentation, https://github.com/bh-rat/steer#readme
Project-URL: Changelog, https://github.com/bh-rat/steer/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/bh-rat/steer/issues
Author-email: Bharat Geleda <bharatgeleda@gmail.com>
License: MIT
License-File: LICENSE
Keywords: SKILL.md,agent-skills,agents,claude,llm,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# steer

**The framework for building Agent Skills.**

[![CI](https://github.com/bh-rat/steer/actions/workflows/ci.yml/badge.svg)](https://github.com/bh-rat/steer/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![Python ≥ 3.11](https://img.shields.io/badge/python-%E2%89%A5%203.11-3776AB)
![Zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)

[Agent Skills](https://agentskills.io) (a `SKILL.md` plus scripts) are the
open standard for packaging agent capabilities, supported by Claude Code,
Codex, Copilot, Cursor, Gemini CLI, and ~40 other clients. The format is
deliberately tiny, which means it ships no batteries: the spec says nothing
about credentials, persistence, context gathering, step enforcement, or
managed processes. Every serious skill hand-rolls some of these.

Steer provides them as components, plus the authoring tools to scaffold,
validate, package, and install skills. Zero dependencies; Python stdlib only.

```
┌─ author-time ──────────────────────┐  ┌─ runtime (CLI or library) ─────────┐
│ steer new        scaffold a skill  │  │ steer secrets   credentials        │
│ steer validate   spec + hygiene    │  │ steer store     per-skill SQLite   │
│ steer package    API-ready zip     │  │ steer context   situational recon  │
│ steer install    into skill dirs   │  │ steer flow      enforced steps     │
│ steer list       what's installed  │  │ steer proc      managed processes  │
└────────────────────────────────────┘  │ steer learn     skills that learn  │
                                        └────────────────────────────────────┘
```

## Why

Steer's components are reverse-engineered from what good skills already
hand-roll in prose and fragile bash (enforced steps, situational recon,
persistent state, credentials, process lifecycles), turned into machinery
you get with one flag.

## Install

```bash
uv tool install steer-ai        # installs the `steer` command
# or: pip install steer-ai
# latest from main: uv tool install git+https://github.com/bh-rat/steer
steer --version
```

Requires Python ≥ 3.11. No runtime dependencies.

## Quickstart

```bash
steer new stripe-report \
  --description "Generates revenue reports from Stripe. Use when the user asks for revenue, MRR, or payment reporting." \
  --with secrets,context,flow,learn --scripts
```

This scaffolds a spec-valid skill:

```
stripe-report/
├── SKILL.md       # frontmatter + body with the components wired in
├── flow.toml      # declarative steps with verify conditions
└── scripts/
    └── example.py # non-interactive, JSON result envelope on stdout
```

The generated `SKILL.md` already tells the agent how to behave:

> 1. **Ground yourself.** Run `steer context` and read the snapshot.
> 2. **Apply past lessons.** Run `steer learn show`; those lessons came
>    from real previous runs.
> 3. **Check credentials.** Run `steer secrets check STRIPE_REPORT_API_KEY
>    --skill stripe-report`. If missing, ask the user to run
>    `steer secrets set ...` (never ask them to paste the value into the
>    chat).
> 4. **Follow the flow.** `steer flow status` → do the step → steps verify
>    themselves against reality; you cannot skip ahead.

For a skill only the human should trigger, `steer new --user-invoked`
sets `disable-model-invocation: true` and validation adapts.

Then:

```bash
steer validate stripe-report     # spec rules, broken refs, secret hygiene
steer install stripe-report      # → .claude/skills/ (project scope)
steer package stripe-report      # → validated zip for the Claude API / claude.ai
```

## Examples

Two complete skills built this way live in [`examples/`](examples/):
[`repo-health`](examples/repo-health) exercises all six components in
one skill (enforced flow, trend memory, credential handoff, managed
preview server, lesson capture), and
[`commit-message`](examples/commit-message) is the minimal user-invoked
counterpoint. Their READMEs show exactly which lines steer generated and
which the author filled in.

## The components

### `steer secrets`: credentials that never live in the skill

Skill directories get zipped and uploaded; credentials must live outside
them. Resolution order: env var → OS keychain (macOS `security` /
Linux `secret-tool`) → `0600` file under `~/.steer/`.

```bash
steer secrets check STRIPE_API_KEY --skill stripe-report   # agent checks
steer secrets set STRIPE_API_KEY --skill stripe-report     # human sets (hidden prompt)
```

```python
from steer import Secrets
key = Secrets("stripe-report").require("STRIPE_API_KEY",
                                       hint="dashboard.stripe.com/apikeys")
# missing -> MissingSecretError whose message tells the agent
# exactly what command to ask the human to run
```

### `steer store`: per-skill SQLite

```bash
steer store put last_run '"2026-06-11"' --skill stripe-report
steer store insert runs '{"month": "may", "total": 1200}' --skill stripe-report
steer store find runs --where month=may --skill stripe-report
```

KV + JSON-document tables + raw SQL. Two scopes: `user`
(`~/.steer/skills/<name>/store.db`) and `workspace`
(`<project>/.steer/<name>/store.db`).

### `steer context`: situational recon in one command

```bash
steer context                # markdown for the agent to read
steer context --json --only git,project,tools
```

One command reports the platform, host agent (Claude Code, Codex, Cursor,
and others), git state, project type (from lockfiles and manifests), tools
on PATH, and a small allowlist of env flags. It never dumps the environment.

### `steer flow`: steps the agent cannot skip

Define the process in `flow.toml`; steps with a `verify` condition complete
only when reality matches, mandate steps are marked explicitly, and marking
is gated on prerequisites:

```toml
[[steps]]
id = "configure"
directive = "Create out/config.json with the data sources"
[steps.verify]
file_exists = "out/config.json"

[[steps]]
id = "review"
directive = "Read the config and confirm the mappings look right"
requires = ["configure"]
```

```bash
steer flow status        # progress bar + current directive
steer flow next          # what to do now
steer flow done review   # mark a mandate step (refused if prereqs incomplete)
```

Verify conditions: `file_exists`, `dir_exists`, `glob`, `command` (exit 0),
`env`. Python API: `steer.Flow` / `steer.Step` for full programmatic control.

### `steer proc`: background processes that don't zombie

```bash
steer proc start web --ready-port 5173 -- npm run dev
steer proc status web
steer proc logs web
steer proc stop web      # TERM → wait → KILL, whole process group
```

It checks readiness by port or log pattern, keeps PID bookkeeping under
`<workspace>/.steer/proc/`, guards against recycled PIDs, and captures logs.

### `steer learn`: skills that improve from their own runs

Tooling exists to improve a skill before it ships, and agents carry runtime
memory; nothing connects the two, so a skill learns nothing from its own
runs. `steer learn` is that connection, a capture → curate → promote loop:
the agent records lessons the moment they happen, reads a bounded digest at
the start of every run, and the author promotes the keepers into the shipped
skill.

```bash
steer learn note "Use the EU endpoint for EU accounts" --kind correction
steer learn show          # ranked digest the SKILL.md tells the agent to read
steer learn confirm 3     # helped → stronger;  dispute → weaker, auto-archives
steer learn promote 3     # human-gated: append to the skill's learnings.md
steer learn run ok && steer learn stats
```

Curation is deterministic (no LLM inside the framework; the agent is the
reflector): duplicates confirm instead of duplicating, disputed-more-than-
confirmed auto-archives, a hard cap evicts the weakest, credential-shaped
notes are refused.

The structure is fixed and inspectable: `~/.steer/skills/<name>/lessons.db`
(source of truth) plus an auto-maintained readable `LEARNINGS.md` mirror,
both outside the skill dir, so lessons survive reinstalls and never ship by
accident. Promoted lessons land in the skill's `learnings.md`, which does
ship.

**Auto-learning:** `steer new my-skill --auto-learn` wires a Claude Code
skill-scoped Stop hook running `steer learn reflect`. When the agent tries
to finish, it deterministically scans the session transcript for corrections
and failed tool calls, and (once) blocks the stop with exact capture
instructions. Capture no longer depends on the agent remembering to do it.

### Result envelope: one output shape for every script

```python
from steer.output import print_envelope
print_envelope("ok", "Report generated",
               data={"rows": 120}, artifacts=["out/report.pdf"])
```

```json
{
  "status": "ok",
  "summary": "Report generated",
  "data": {"rows": 120},
  "artifacts": ["out/report.pdf"]
}
```

## Validation

`steer validate` checks the open spec's hard rules (name format/length and
directory match, description 1-1024 chars, no XML), progressive-disclosure
budgets (<500-line body), broken file references, portability (Claude-Code-
only frontmatter), thin trigger descriptions, duplicated paragraphs across
SKILL.md and references (keep one source of truth), orphaned `references/`
files nothing points to, and secret hygiene: credential-looking files
inside a skill are warnings normally and hard errors at packaging time.
`steer package` refuses to ship them.

## Library use

Everything the CLI does is importable (`from steer import Skill, Flow,
Secrets, Store, validate_skill, discover`) for building your own skill
tooling on top.

## What steer is not

Not a registry or installer ecosystem (use `npx skills`, Tessl, or plugin
marketplaces; steer sits upstream of them), not an eval harness (yet), and
not useful at runtime for pure-knowledge skills (a style guide needs no
database, though steer still helps author and validate it).

## Roadmap

Skill-to-skill dependencies / shared libraries, `steer test`
(trigger-regression + cross-runtime checks), signing/provenance, TypeScript
SDK, PyPI release.

## Docs & contributing

Full documentation lives in [`docs/`](docs/) (introduction, quickstart, a
page per component, and the authoring guide, including the checklist for
writing skill bodies: trigger, structure, steering, pruning). Contributions
are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go to
[SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)
