Rust · MIT · crates.io/crates/skillterm
skillterm transforms your terminal into an intelligent assistant. It uses a headless agent runtime — Claude Code or Codex — to generate Claude-compatible SKILL.md files from man pages, web documentation, and SaaS APIs, then plugs those skills into zsh, bash, and fish tab completion.
The agent architecture, in one line
skillterm cli → claude code (headless) → WebSearch · WebFetch · Bash · Read/Write → SKILL.md
skillterm is the orchestrator. The headless agent runtime brings tool use — web search, web fetch, bash, file I/O — that skillterm would otherwise have to re-implement around a raw LLM API.
What skillterm actually ships
skillterm calls a headless agent runtime — Claude Code by default, Codex as an alternative — so the generator gets web search, web fetch, bash, and file I/O for free. The skillterm CLI is the orchestrator; the agent does the reasoning.
Every generation loads two bundled skills as context: skill-creator (the SKILL.md format spec and quality checklist) and saas-detector (how to classify a tool and find its documentation). Improving skillterm means improving these skills, not rewriting code.
eval "$(skillterm init <shell>)" wires skillterm into your shell. The complete subcommand is what the shell hook calls when you press Tab; it returns contextual completions sourced from the matching SKILL.md.
Each skill is a SKILL.md file with YAML frontmatter (name, description) and a markdown body. The format follows the public Claude Agent Skills convention, so the same file an agent uses to reason can be read by a human.
skillterm generate works from a system man page (default), a specific documentation URL (--from-url), or an open web search (--from-search). Dry-run, force overwrite, and provider override are all CLI flags.
skills are managed like packages: install from a registry or a GitHub reference (gh:user/repo), search local and remote, list installed, publish your own. The registry layer is documented; the design point is that skills are shareable units of knowledge.
Install
skillterm itself is a Rust binary. You also need an agent runtime — Claude Code (recommended) or Codex — installed and available on your PATH.
cargo install skillterm Native Rust install; primary distribution per the README.
cargo install --path crates/skillterm-cli Clone github.com/neul-labs/skillterm and build the CLI crate.
npm install -g @anthropic-ai/claude-code Required agent runtime when using the default runtime = "claude-code".
npm install -g @openai/codex Alternative agent runtime when configuring runtime = "codex".
Quickstart
Wire the shell hook, set the runtime's API key, then ask skillterm to generate a skill.
# Wire the shell hook (zsh shown; bash & fish supported too) eval "$(skillterm init zsh)" # Configure the agent runtime export ANTHROPIC_API_KEY="sk-ant-..." # Generate a skill — agent searches, fetches, writes SKILL.md skillterm generate kubectl # Use the skill via tab completion kubectl get <TAB> # → completions sourced from ~/.skillterm/skills/kubectl/SKILL.md
How one generation flows
01
skillterm CLI parses the request ("generate stripe"), sets the working directory to ~/.skillterm/skills/, and pins the prompt.
02
Two meta-skills — skill-creator and saas-detector — are loaded into the agent context, so the agent knows the SKILL.md format and how to classify a tool.
03
Claude Code (or Codex) is invoked headless. The agent has WebSearch, WebFetch, Bash, and Read/Write available.
04
Agent classifies the tool, searches the web for canonical docs, fetches and parses them, runs man / --help as needed.
05
Agent writes the file to ~/.skillterm/skills/<tool>/SKILL.md, following the format spec from skill-creator. skillterm captures the result.
06
Later, when you press Tab on a matching command, the shell hook calls `skillterm complete`, which sources completions from the SKILL.md.
Crate layout: skillterm-cli (binary), skillterm-core (skill parsing & types), skillterm-agent (runtimes), skillterm-shell (shell integration), skillterm-registry (registry client).
CLI surface
Pulled straight from docs/reference/cli.md. The CLI is small on purpose: most behavior happens through agent generation and the SKILL.md format.
| Command | What it does |
|---|---|
| skillterm generate | Generate a SKILL.md via the agent runtime (man, URL, or web search). |
| skillterm complete | Called by the shell hook — returns Tab completions for the current line. |
| skillterm search | Search skills locally and in the registry, by query, category, or author. |
| skillterm install | Install from the registry (name, name@version) or GitHub (gh:user/repo). |
| skillterm publish | Publish a skill directory to the registry (with --dry-run validation). |
| skillterm list | List installed skills, by category, sorted by name / updated / size. |
| skillterm show | Print details (or --raw, --json, --path) for a single installed skill. |
| skillterm remove | Remove an installed skill (with --force to skip confirmation). |
| skillterm update | Update one or all skills, or just --check for availability. |
| skillterm init | Emit the shell integration script for bash, zsh, or fish. |
| skillterm config | get / set / list / edit / test-provider configuration values. |
| skillterm auth | Registry login / logout / status / token. |
| skillterm cache | Clear or inspect the local docs / man / registry caches. |
Honest comparisons
There are good neighbours in the AI-CLI space. We compare two we can describe fairly from public docs.
shell-gpt asks an LLM to generate a one-shot shell command. skillterm asks an agent runtime to generate persistent SKILL.md files that drive Tab completion on every future invocation.
mods (Charmbracelet) pipes prompts to LLMs from the shell with elegant Markdown output. skillterm targets a different surface — generating reusable skills that integrate into completion.
FAQ
A skill is a directory containing a SKILL.md file (and optionally a references/ folder or scripts/ folder). SKILL.md has YAML frontmatter — at minimum name and description — and a markdown body with overview, commands, examples, best practices. The format follows the Claude Agent Skills convention, so the same file can be loaded as agent context or read by a human as documentation.
Two are documented: Claude Code (the primary runtime, configured as runtime = "claude-code") and Codex (the alternative, runtime = "codex"). Both are configured per-runtime in ~/.skillterm/config.toml with binary path, model, and timeout. The README treats Claude Code as the recommended setup.
Three are listed in the README: zsh, bash, and fish. You install the hook with skillterm init <shell> — the zsh and bash hooks are eval-piped, the fish one is sourced. The shell hook calls skillterm complete on each Tab; skillterm returns completions sourced from any matching local SKILL.md.
skillterm does not call the Anthropic API directly. It invokes the Claude Code CLI in headless mode and lets that agent use its built-in tools: WebSearch (locate docs), WebFetch (read docs), Bash (man / --help), Read/Write (skills directory). The README is explicit that the "key insight" is using Claude Code as the runtime rather than reimplementing those tools.
skillterm searches three directories in order: project (./.skillterm/skills/), user (~/.skillterm/skills/), and system (/usr/share/skillterm/skills/). Project skills win, which lets you pin per-repo overrides. Bootstrap meta-skills ship with the binary and live separately.
Yes — MIT-licensed. Source at github.com/neul-labs/skillterm. Distribution: cargo install skillterm (the README also references homebrew, npm, and pypi packaging directories in the repo). It is a workspace of Rust crates: skillterm-cli, skillterm-core, skillterm-agent, skillterm-shell, and skillterm-registry.
Partially. The agent runtime still has bash and local file access, so skillterm generate can build a skill from a system man page and --help output. Web search and web fetch are gated by the [agent.permissions] block in config.toml; turn allow_web_search and allow_web_fetch off and the agent will work from local sources only.
MIT-licensed, single binary install, SKILL.md as the durable artefact. Generate once, complete forever.