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)

# 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: 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 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.

• 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.

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
• Hooks: lifecycle hooks for Claude Code (formatting, logging, security, notifications)
• Skill evolution: harvest, optimize, A/B test and merge skills (see docs/cascade.md)

Installation

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

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:

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

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

List Available Skills

# 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

# 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

knowhow search python
knowhow search "lab notebook"

Create a New Skill

# 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

knowhow uninstall skill-name

Manage Hooks

# 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

# 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:

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

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 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:

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:

---
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:

---
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):

---
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:

---
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

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

# Install pre-commit hooks
pre-commit install

Pre-commit Hooks

This project uses pre-commit 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

# Run all tests
pytest

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

Linting and Formatting

We use Ruff for both linting and formatting:

# 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 - The AI coding agent built for the terminal. Open-source, provider-agnostic, with 30k+ GitHub stars.
• Claude Code - Anthropic's agentic coding tool that lives in your terminal. Understands your codebase and helps you code faster.
• Codex CLI - OpenAI's lightweight coding agent that runs in your terminal. See OpenAI adopts "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 - Vercel's Node CLI and the 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 (agentskills/agentskills) - The open SKILL.md format that knowhow validate checks against.

• anthropics/skills - Anthropic's public collection of Agent Skills; installable with knowhow add anthropics/skills.

• skillz (MCP server) - 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 - A proof-of-concept Python CLI for managing AI agent skills.

• openskills - Another universal skills loader (I have not tried this yet).

• opencode-skills - With OpenCode you may get better performance with this plugin (this is what I use). See also the OpenCode feature request.

• 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.