Metadata-Version: 2.5
Name: knowhow
Version: 0.2.0
Summary: Install and manage AI agent skills from any git repo (npx skills compatible) for Claude Code, Codex, OpenCode, Gemini and more
Project-URL: Homepage, https://github.com/jkitchin/knowhow
Project-URL: Documentation, https://github.com/jkitchin/knowhow#readme
Project-URL: Repository, https://github.com/jkitchin/knowhow
Project-URL: Issues, https://github.com/jkitchin/knowhow/issues
Author-email: John Kitchin <jkitchin@andrew.cmu.edu>
License: MIT
License-File: LICENSE
Keywords: ai,claude,cli,llm,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.4.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pre-commit>=4.6.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: ruff>=0.15.18; extra == 'dev'
Provides-Extra: templates
Requires-Dist: jinja2>=3.1.6; extra == 'templates'
Description-Content-Type: text/markdown

# Knowhow

<img src="https://raw.githubusercontent.com/jkitchin/knowhow/main/knowhow.svg" alt="knowhow logo: KNOWHOW above a terminal running uvx knowhow add" width="300">

[![Tests](https://github.com/jkitchin/knowhow/actions/workflows/test.yml/badge.svg)](https://github.com/jkitchin/knowhow/actions/workflows/test.yml)
[![Lint](https://github.com/jkitchin/knowhow/actions/workflows/lint.yml/badge.svg)](https://github.com/jkitchin/knowhow/actions/workflows/lint.yml)
[![codecov](https://codecov.io/gh/jkitchin/knowhow/graph/badge.svg)](https://codecov.io/gh/jkitchin/knowhow)


Install AI agent skills, slash commands, subagents, hooks and MCP servers from any git
repository with one command. There's nothing to install first and no repository to clone.
Works with Claude Code, VS Code (GitHub Copilot), Codex, OpenCode, Gemini CLI, Cursor and more.

> **Note:** Currently only tested on Claude Code and OpenCode. Please report issues for other agents.

This repository is both the `knowhow` tool and a collection of 44 skills, plus commands, hooks
and agents, for scientific computing, materials science, lab automation and research workflows.

## Install skills from any repo (no setup)

```bash
# List what a repository offers, then install a skill into this project
uvx knowhow add jkitchin/knowhow --list
uvx knowhow add jkitchin/knowhow --skill fairchem

# Install for your user (all projects), several skills, no prompts
uvx knowhow add jkitchin/knowhow -s pycse -s python-plotting -g -y

# Any compatible repo, URL or local path works
uvx knowhow add someone/their-skills@their-skill
uvx knowhow add https://github.com/o/r/tree/main/skills/foo

# Slash commands, subagents and hooks (installed for Claude Code)
uvx knowhow add jkitchin/knowhow --command commit --subagent code-reviewer
uvx knowhow add jkitchin/knowhow --hook black-on-save   # shows the script for review first

# MCP servers, from the repo's .mcp.json, for every selected agent
uvx knowhow add someone/repo --mcp their-server -a claude-code -a vscode -a cursor

uvx knowhow find plotting   # search skills.sh / GitHub
uvx knowhow installed       # everything knowhow installed (project + global)
uvx knowhow check           # any upstream changes?
uvx knowhow upgrade         # apply them
uvx knowhow remove fairchem
uvx knowhow remove --all    # remove everything knowhow installed in this project (-g: global)
```

Until `knowhow` is published on PyPI, use
`uvx --from git+https://github.com/jkitchin/knowhow knowhow add ...`.

- **Compatible with [`npx skills`](https://github.com/vercel-labs/skills):** skills use the same
  repository layout, install locations and lock files, so the two tools can be mixed. A skill
  is copied once to `.agents/skills/<name>`, which VS Code, Codex, OpenCode, Gemini CLI,
  Cursor and Copilot read directly, and symlinked into `.claude/skills/<name>`. With `-g` the same
  happens under `~/`.
- **Tracked:** installs are recorded in `skills-lock.json` (commit it) and
  `.claude/knowhow-lock.json`. `check` and `upgrade` use these to find upstream changes.
- **Publish your own:** any git repo with `SKILL.md` files works. Follow the
  [guide to creating compatible skill repositories](docs/publishing-skills.md) and
  check your repo with `uvx knowhow validate .`.
- **Shortcuts:** `knowhow config set alias.kitchin jkitchin/knowhow` lets you write
  `knowhow add kitchin -s pycse`.

The `skillz` command still works as an alias of `knowhow`.

### Safety

Skills, hooks and MCP servers come from other people's repositories and can run code on
your machine. knowhow is careful about what it changes:

- **It never replaces your own files.** If a skill folder, command, subagent, hook or MCP
  server with the same name exists and wasn't installed by knowhow (or npx skills), `add`
  lists it and stops. Pass `--force` to replace it.
- **It only removes what it installed.** `remove` refuses names that aren't in a knowhow
  lock file unless you pass `--force`. Without a terminal it requires `-y`.
- **You review code that runs.** Hooks and MCP servers must be named explicitly. Their
  scripts or config are shown, with terminal escape codes stripped, and need confirmation
  (or `-y`).
- **It won't corrupt your config files.** `settings.json`, MCP configs and lock files are
  only edited if they parse cleanly; a damaged file stops knowhow with a message rather
  than being replaced. Changes are written atomically. `<file>.bak` keeps each file as it
  was before the most recent knowhow command, so you may want `*.bak` in `.gitignore`.
- **It stays inside the project.** Symlinked config files are updated in place, which
  keeps dotfiles setups working. In a project, though, knowhow refuses any file that links
  outside the project. Lock files record only which agents an MCP server went to, never
  file paths, so a cloned repository's lock can't redirect where knowhow writes.
- **Files are confined to the skill.** Only files inside the skill's directory are copied.
  Symlinks pointing outside the repository, and directory symlinks, are skipped. Skill
  scripts are never run during installation.
- **Upgrades show what changed.** `upgrade` lists added, changed and removed files. It asks
  before applying new or changed scripts, and needs `-y` without a terminal.

## MCP servers

`--mcp NAME` installs an MCP server from the source repo's `.mcp.json` (or `mcp/*.json`)
into each selected agent's own config file. Agents come from `-a`, or else from
`default_platform` or detection. knowhow translates the config to each agent's format.

| Agent (`-a`) | Project file | Global file (`-g`) | `${VAR}` written as |
|---|---|---|---|
| `claude-code` | `.mcp.json` | via `claude mcp add-json --scope user` | `${VAR}` |
| `vscode` | `.vscode/mcp.json` (`servers`) | VS Code user `mcp.json` | `${env:VAR}` |
| `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` | `${env:VAR}` |
| `codex` | `.codex/config.toml` | `~/.codex/config.toml` | `env_vars`, `bearer_token_env_var`, `env_http_headers` |
| `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` | `${VAR}` (not verified) |
| `opencode` | `opencode.json(c)` (`mcp`) | `~/.config/opencode/opencode.json` | `{env:VAR}` |
| `github-copilot` | `.mcp.json` | `~/.copilot/mcp-config.json` | `${VAR}` |
| `windsurf` | (global only) | `~/.codeium/windsurf/mcp_config.json` | `${VAR}` (not verified) |

- **Existing files are respected.** A file is only edited if it parses cleanly, and the
  previous version is kept as `.bak`. Files with comments (JSONC) are never rewritten: that
  agent is skipped and knowhow prints the snippet to paste yourself. For Codex's TOML, knowhow
  appends or removes only the server's own table, and keeps your comments.
- **Project files are only created for agents set up in that project.** Without `-a`, an
  agent needs its folder (e.g. `.vscode/`) to get a project file. Name an agent with `-a` to
  create its file anyway.
- **Untranslatable values are flagged.** If a value can't be expressed for an agent (for
  example `${VAR}` inside Codex `args`), you get a warning instead of a broken config.
- **Removal reaches every place.** `remove --mcp NAME` removes the server from every file it
  was written to. `knowhow installed` shows each location and its status.

## Seeing and removing what's installed

`knowhow installed` lists everything knowhow installed for this project and for your user.
It works offline from the lock files and checks each item is still on disk.
`--untracked` also shows items knowhow didn't install: skills and Claude Code
commands, subagents and hooks in agent folders, and MCP servers in every agent's MCP
config. Claude Code's global MCP servers live in `~/.claude.json`, managed by `claude mcp`,
and aren't read; they show as `registered`.

| Installed with | Remove with | What gets removed |
|---|---|---|
| `add -s NAME` (project) | `remove NAME` | `.agents/skills/NAME`, agent links/copies (`.claude/skills/NAME`, ...), lock entry |
| `add -s NAME -g` | `remove NAME -g` | the same under `~/` |
| `add ... -a custom-platform` | `remove NAME [-g]` | the copy in the platform's `skills_dir` / `project_skills_dir` |
| `add --command N` / `--subagent N` | `remove --command N` / `--subagent N` | `.claude/commands/N.md` / `.claude/agents/N.md` |
| `add --hook N` | `remove --hook N` | `.claude/hooks/N/` and every `settings.json` entry for it |
| `add --mcp N` | `remove --mcp N` | the server in every agent config it was written to (see [MCP servers](#mcp-servers)) |
| everything from one repo | `remove owner/repo [-g]` | all of the above that came from that source |
| everything | `remove --all [-g]` | all of the above, in one scope |
| legacy `install` / `hooks install` / `agents install` | `uninstall` / `hooks uninstall` / `agents uninstall` | (not tracked in lock files; `remove NAME --force` also works) |

`remove` only touches things recorded in a lock file. Pass `--force` for anything else.
Other servers in `.mcp.json`, other hooks in `settings.json`, and your own files are left
alone. To uninstall knowhow itself, run `uv tool uninstall knowhow`. Installed skills stay
until you remove them, so run `knowhow remove --all` and `knowhow remove --all -g` first if
you want a clean slate.

## Features

- **Remote install**: `add` skills, commands, subagents, hooks and MCP servers from GitHub, GitLab, any git URL or a local path
- **Updates**: `check` and `upgrade` against lock files; `remove` by name or by source
- **Search**: `find` searches skills.sh and GitHub; `search` searches a local skills repository
- **Create**: interactive wizard or AI-assisted creation of skills, commands, hooks and agents
- **Validate**: `knowhow validate` checks a repo against the Agent Skills spec and how installers will see it (CI-friendly exit codes)
- **Multi-agent**: Claude Code, VS Code, Codex, OpenCode, Gemini CLI, Cursor, GitHub Copilot, Goose, Windsurf, plus [custom platforms](#custom-platforms)
- **Hooks**: lifecycle hooks for Claude Code (formatting, logging, security, notifications)
- **Skill evolution**: harvest, optimize, A/B test and merge skills (see [docs/cascade.md](docs/cascade.md))

## Installation

You don't need to install anything to use `uvx knowhow ...`. To keep `knowhow` on your PATH:

```bash
uv tool install knowhow          # or: pipx install knowhow
# before the PyPI release:
uv tool install git+https://github.com/jkitchin/knowhow
```

For development, from a clone of this repository:

```bash
uv pip install -e ".[dev]"
```

## Working with a local skills repository

The commands below work from a local clone of a skills repository, such as this one. Use
them when you are developing skills. For plain installs, `knowhow add` (above) is simpler.

### Configure Repository Path

```bash
knowhow config set repository /path/to/your/clone
```

### List Available Skills

```bash
# List all skills and commands
knowhow list

# List only skills
knowhow list --type skill

# List only from repository
knowhow list --source repository
```

### Install a Skill

```bash
# Install to Claude Code (default)
knowhow install skill-name

# Install to OpenCode
knowhow install skill-name --platform opencode

# Install to project directory (.claude/skills/)
knowhow install skill-name --target project

# Preview before installing
knowhow install skill-name --dry-run
```

### Search for Skills

```bash
knowhow search python
knowhow search "lab notebook"
```

### Create a New Skill

```bash
# Interactive mode
knowhow create --type skill

# With name specified
knowhow create --type skill --name my-awesome-skill

# AI-assisted creation using Claude CLI
knowhow create --type skill --name my-skill --prompt "A skill for analyzing Python code style"
```

### Uninstall a Skill

```bash
knowhow uninstall skill-name
```

### Manage Hooks

```bash
# List available hooks
knowhow hooks list --target repo

# Install a hook
knowhow hooks install lab-notebook

# Create a hook (with AI)
knowhow hooks create my-hook --event PostToolUse --prompt "Format Python with black"
```

### Manage Agents

```bash
# List available agents
knowhow agents list --target repo

# Install an agent
knowhow agents install code-reviewer

# Create an agent (with AI)
knowhow agents create my-agent --prompt "An agent that reviews security vulnerabilities"
```

## Configuration

### Custom platforms

You can add any agent that reads skills from a directory by defining it in the config
file, then use it like a built-in:

```yaml
default_platform: picoclaw        # optional: use it when --platform / -a is omitted
platforms:
  picoclaw:
    skills_dir: ~/picoclaw/docker/data/workspace/skills
    commands_dir: ~/picoclaw/docker/data/workspace/commands
    project_skills_dir: .picoclaw/skills
```

```bash
knowhow add jkitchin/knowhow -s pycse -a picoclaw -g    # copies, never symlinks
knowhow install pycse --platform picoclaw
```

- An unknown platform name is an error. It never falls back to the Claude directories.
- A command that needs a directory you haven't configured, such as `hooks_dir` or
  `project_skills_dir`, tells you which key to set.
- Changing `skills_dir` or `project_skills_dir` for a built-in platform (claude, codex, ...)
  overrides where `knowhow add` installs for it.

See [example-config.yaml](example-config.yaml) for every key.

### Config file

Configuration is stored in `~/.config/skillz/config.yaml` (the path keeps the original name
so existing setups keep working).

Default configuration:

```yaml
default_platform: claude

personal_skills_dir: ~/.claude/skills
personal_commands_dir: ~/.claude/commands
project_skills_dir: .claude/skills
project_commands_dir: .claude/commands
default_target: personal
aliases: {}            # e.g. {kitchin: jkitchin/knowhow} for `knowhow add kitchin ...`

platforms:
  claude:
    skills_dir: ~/.claude/skills
    commands_dir: ~/.claude/commands
  opencode:
    skills_dir: ~/.config/opencode/skills
    commands_dir: ~/.config/opencode/command
  codex:
    skills_dir: ~/.codex/skills
    commands_dir: ~/.codex/commands
  gemini:
    skills_dir: ~/.config/gemini/skills
    commands_dir: ~/.config/gemini/commands
```

## Skills Format

Skills are directories containing a `SKILL.md` file with YAML frontmatter:

```markdown
---
name: my-skill
description: A clear description of what this skill does and when to use it
allowed-tools: ["*"]  # Optional: restrict available tools
---

# Skill Content

Detailed instructions for Claude on how to use this skill...
```

### Requirements

- `name`: lowercase, hyphens only, max 64 characters
- `description`: clear explanation, max 1024 characters
- Directory must contain `SKILL.md`

## Commands Format

Commands are markdown files with optional YAML frontmatter:

```markdown
---
description: Brief description for /help
model: sonnet  # Optional: sonnet, opus, or haiku
allowed-tools: ["*"]  # Optional
argument-hint: <your-arg>  # Optional: autocomplete help
---

# Command Content

Command prompt content here...

Use $ARGUMENTS or $1, $2, etc. for parameters.
```

## Hooks Format

Hooks are directories containing a `HOOK.md` file and a script (`hook.py` or `hook.sh`):

```markdown
---
name: my-hook
description: Brief description of what this hook does
event: PostToolUse  # PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, etc.
matcher: Write      # Optional: filter by tool name
timeout: 30         # Optional: timeout in seconds
---

# Hook Documentation

Details about when and how this hook runs...
```

### Available Hook Events

- `PreToolUse` / `PostToolUse`: Before/after tool execution
- `UserPromptSubmit`: When user submits a prompt
- `Stop`: When Claude needs user input
- `SessionStart` / `SessionEnd`: Session lifecycle
- `Notification`: For notifications

## Agents Format

Agents are markdown files with YAML frontmatter:

```markdown
---
name: my-agent
description: Clear description of what this agent does
tools: Read, Write, Edit, Grep, Glob
model: sonnet  # sonnet, opus, or haiku
---

# Agent Instructions

Detailed instructions for this specialized agent...
```

## Project Structure

```
knowhow/                  # repository
├── knowhow/               # Python CLI package
│   ├── commands/          # CLI command implementations (add.py = add/remove/check/upgrade/find)
│   ├── sources.py         # Parse owner/repo, URLs, local paths
│   ├── fetch.py           # Shallow git clone / GitHub API
│   ├── discovery.py       # Find SKILL.md skills (npx-skills compatible)
│   ├── extras.py          # Commands, subagents, hooks, MCP servers
│   ├── installer.py       # Canonical copy + agent symlinks
│   ├── lock.py            # Lock files
│   ├── agents_registry.py # Supported agents and their paths
│   ├── config.py          # Configuration management
│   ├── validator.py       # Skill/command/hook/agent validation
│   └── utils.py           # Helper functions
├── skills/                # Skill repository
│   ├── academic/
│   ├── programming/
│   └── research/
├── commands/              # Command repository
├── hooks/                 # Hooks repository
│   ├── lab-notebook/
│   ├── prettier-on-save/
│   └── ...
├── agents/                # Agents repository
│   ├── code-reviewer.md
│   ├── debugger.md
│   └── ...
├── templates/             # Templates for new skills/hooks/agents
├── docs/                  # Documentation
└── tests/                 # Test suite
```

## Development

### Setup Development Environment

```bash
# Install with development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Pre-commit Hooks

This project uses [pre-commit](https://pre-commit.com/) to automatically run linting and formatting checks before each commit. The hooks will:

- Run `ruff check --fix` to fix linting issues
- Run `ruff format` to format code

If any changes are made by the hooks, the commit will fail. Simply stage the changes and commit again.

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage report
pytest --cov=knowhow --cov-report=html
```

### Linting and Formatting

We use [Ruff](https://docs.astral.sh/ruff/) for both linting and formatting:

```bash
# Check for linting issues
ruff check .

# Auto-fix linting issues
ruff check --fix .

# Check formatting
ruff format --check .

# Format code
ruff format .
```

## Available Skills

See the `skills/` directory, or run `uvx knowhow add jkitchin/knowhow --list`:

- **Programming & materials science**: ASE, pymatgen, VASP, FAIRChem, pycalphad, IDAES, JAX, materials properties, Python best practices, plotting, optimization (single and multiobjective), regression & statistics, Emacs Lisp, Claude-Light
- **Laboratory automation**: Opentrons (API, gripper, heater-shaker, thermocycler, temperature module, magnetic block, absorbance reader)
- **Research**: literature review, scientific data extraction, scientific reviewer, materials databases, scientific workflows, electronic lab notebooks, citation verification, design of experiments, pycse
- **Communication & creative**: scientific writing, presentations, image generation, video storytelling, ElevenLabs audio, brainstorming
- **Development & productivity**: version control, code review, TDD, Ralph Wiggum autonomous loop, troubleshooting, planning
- **Academic**: PhD qualifier review

## Available Hooks

See the `hooks/` directory for available hooks:

- **lab-notebook**: Generate lab notebook entries from Claude Code sessions
- **prettier-on-save**: Auto-format JS/TS/CSS/JSON files with Prettier
- **black-on-save**: Auto-format Python files with Black
- **protect-secrets**: Block writes to sensitive files like .env
- **bash-logger**: Log all bash commands for audit
- **notify-done**: Desktop notification when Claude needs input

## Available Agents

See the `agents/` directory for available agents:

- **code-reviewer**: Analyzes code for quality, security issues, and best practices
- **debugger**: Traces issues through code, analyzes errors, suggests fixes
- **literature-searcher**: Searches academic papers and technical resources
- **test-writer**: Generates comprehensive test cases and suites
- **doc-writer**: Creates documentation, READMEs, and API docs

## Available Commands

See the `commands/` directory for slash commands:

### Git & Workflow
- **/commit**: Generate commit message from staged changes
- **/pr**: Generate PR description from branch commits
- **/changelog**: Generate changelog entry for recent changes

### Code Quality
- **/review**: Quick code review of file or selection
- **/explain**: Explain what code does in plain English
- **/refactor**: Suggest refactoring improvements
- **/fix**: Diagnose and fix a specific error

### Documentation
- **/doc**: Generate docstrings/comments for code
- **/readme**: Generate or update README content
- **/api**: Generate API documentation

### Research
- **/cite**: Format citation from URL or DOI
- **/lab-entry**: Create formatted lab notebook entry
- **/summarize**: Summarize file, PR, or conversation

### Analysis
- **/deps**: Analyze project dependencies
- **/todo**: Extract TODOs from codebase
- **/find-usage**: Find where function/class is used

## Contributing

Contributions are welcome! Please:

1. Follow the skill/command format requirements
2. Add tests for new functionality
3. Update documentation
4. Run linters before submitting

## License

MIT License - see LICENSE file for details

## Support

- Report issues: https://github.com/jkitchin/knowhow/issues
- Documentation: https://github.com/jkitchin/knowhow#readme

## Related Projects

### Supported Platforms

Knowhow manages skills and commands for these AI coding assistants:

- **[OpenCode](https://github.com/sst/opencode)** - The AI coding agent built for the terminal. Open-source, provider-agnostic, with 30k+ GitHub stars.
- **[Claude Code](https://github.com/anthropics/claude-code)** - Anthropic's agentic coding tool that lives in your terminal. Understands your codebase and helps you code faster.
- **[Codex CLI](https://github.com/openai/codex)** - OpenAI's lightweight coding agent that runs in your terminal. See [OpenAI adopts "skills"](https://simonwillison.net/2025/Dec/12/openai-skills/) for details on their skills implementation.
- **Gemini** - Google's AI assistant.
- **VS Code** (GitHub Copilot in VS Code) reads `.agents/skills` and `~/.agents/skills`, so skills installed with `knowhow add` work there out of the box; `-a vscode` targets it explicitly.
- Cursor, GitHub Copilot, Goose and Windsurf are supported targets for `knowhow add` skills.

### Related Skills Projects

- **[npx skills](https://github.com/vercel-labs/skills)** - Vercel's Node CLI and the [skills.sh](https://skills.sh) directory. `knowhow add` was modeled on it and follows its layout, install paths and lock files, so either tool sees what the other installed. Use it if you prefer Node; knowhow adds commands, subagents, hooks and MCP servers.
- **[Agent Skills specification](https://agentskills.io)** ([agentskills/agentskills](https://github.com/agentskills/agentskills)) - The open SKILL.md format that `knowhow validate` checks against.
- **[anthropics/skills](https://github.com/anthropics/skills)** - Anthropic's public collection of Agent Skills; installable with `knowhow add anthropics/skills`.
- **[skillz (MCP server)](https://github.com/intellectronica/skillz)** - An MCP server that loads skills into clients without native skill support. It owns the `skillz` name on PyPI, which is why this tool is published as knowhow.
- **[skillpack-cli](https://pypi.org/project/skillpack-cli/)** - A proof-of-concept Python CLI for managing AI agent skills.
- **[openskills](https://github.com/numman-ali/openskills)** - Another universal skills loader (I have not tried this yet).
- **[opencode-skills](https://www.npmjs.com/package/opencode-skills)** - With OpenCode you may get better performance with this plugin (this is what I use). See also the [OpenCode feature request](https://github.com/sst/opencode/issues/3235).

- **[Superpowers](https://github.com/obra/superpowers)** - A complete software development workflow framework for Claude Code with composable skills for design, TDD, code review, and integration. This project was an early motivation to develop this project.

## Credits

Created by John Kitchin for managing AI assistant skills across different LLM platforms.
