neoskills

Homebrew-style skill manager for AI coding agents.

neoskills manages portable skill definitions across agent ecosystems (Claude Code, OpenCode, OpenClaw). Browse skills in one place, sync to GitHub, deploy selectively via symlinks, and discover relationships through a built-in ontology graph.

---

Table of Contents

• Installation
• Quick Start
• How It Works
• Ontology Layer
• Agent Targets
• Operating Modes
• CLI Reference
• Development

---

Installation

From PyPI (recommended)

pip install neoskills

Or with uv:

uv tool install neoskills

From source

git clone https://github.com/neolaf2/neoskills
cd neoskills
uv sync --dev
uv run neoskills --help

Requirements

• Python 3.13+ (required)
• Git (for tap operations)
• uv (recommended for development)

---

Quick Start

# 1. Initialize the workspace
neoskills init

# 2. Add a tap (a git-hosted skill repository)
neoskills tap https://github.com/your-org/my-skills

# 3. Browse and search
neoskills list                          # all skills in your taps
neoskills list --linked                 # what's deployed to your agent
neoskills search "document processing"  # cross-tap search

# 4. Deploy a skill to your agent
neoskills install kstar-loop            # copies to tap + symlinks to agent

# 5. Create your own skill
neoskills create my-new-skill -d "What it does" --type task

# 6. Check system health
neoskills doctor

What just happened?

neoskills init created ~/.neoskills/ with a default tap. install found the skill in a tap and created a symlink into your agent’s skill directory (e.g., ~/.claude/skills/). Your agent can now use the skill. create scaffolded a new skill with SKILL.md + ontology.yaml.

---

How It Works

Architecture

~/.neoskills/                         # Workspace root
├── config.yaml                       # Targets, taps, defaults
├── taps/                             # Git-cloned skill repositories
│   ├── mySkills/                     # Default tap
│   │   └── skills/
│   │       └── /
│   │           ├── SKILL.md          # Skill definition (frontmatter + body)
│   │           ├── ontology.yaml     # Graph metadata (optional, recommended)
│   │           ├── scripts/          # Executable code (optional)
│   │           ├── references/       # Supporting docs (optional)
│   │           └── assets/           # Media/templates (optional)
│   └── /                 # Additional skill sources
└── cache/                            # Backups and temp storage

Deployment model

Skills are deployed to agents via per-skill symlinks (zero-copy, instantly reversible):

~/.claude/skills/kstar-loop  -->  ~/.neoskills/taps/mySkills/skills/kstar-loop

This means:

• One source of truth in your tap (version controlled with git)
• Multiple agents can link the same skill simultaneously
• No copying – changes to the tap are immediately reflected
• Reversible – neoskills unlink removes the symlink, nothing else

Skill anatomy

Every skill is a directory with at minimum a SKILL.md:

# SKILL.md frontmatter
---
name: my-skill
description: "What this skill does"
author: "Your Name"
tags: [productivity, automation]
targets: [claude-code]
---

# My Skill

Instructions, prompts, and documentation that the agent will read.

Optionally, an ontology.yaml sidecar adds graph metadata (type, domain, lifecycle, edges, versioning). See Ontology Layer.

---

Ontology Layer

The ontology adds a property graph over your skills – nodes and typed edges stored as ontology.yaml sidecar files. No external database. The graph materializes from the filesystem at runtime.

Progressive enrichment

Skills don’t need full metadata on day one:

Discovery

# Faceted search
neoskills ontology discover --domain agent-architecture --state operational
neoskills ontology discover --type meta --text "compiler"

# Load and inspect the full graph
neoskills ontology load     # prints summary: skills, edges, domains
neoskills ontology stats    # JSON statistics

Dependencies

neoskills ontology deps kstar-loop --transitive    # what it requires
neoskills ontology rdeps kstar-planner --tree       # what depends on it
neoskills ontology add-edge skill-a skill-b -t requires

Edge types: requires, extends, composes_with, conflicts_with, supersedes, derived_from.

Lifecycle

Skills move through a state machine:

candidate --> validated --> operational --> refined --> deprecated --> archived

neoskills ontology lifecycle                                          # all skills by state
neoskills ontology transition my-skill validated --reason "tested"    # change state

Composition

# Compose skills into a pipeline
neoskills ontology compose source-text-to-markdown research-md-to-latex \
  --mode pipeline --name md-to-paper

# Plan a decomposition
neoskills ontology split monolithic-skill sub-a sub-b sub-c

Versioning

neoskills ontology version kstar-loop --bump minor   # 0.1.0 -> 0.2.0

Visualization & export

neoskills ontology graph kstar-loop --depth 2 --format mermaid
neoskills ontology export --format json --output graph.json
neoskills ontology export --format dot                              # Graphviz

Validation

neoskills ontology validate   # broken edges, cycles, conflicts

Auto-enrichment

neoskills ontology enrich my-skill              # single skill, L0 -> L1
neoskills ontology enrich --all --level L1 --dry-run   # preview batch
neoskills ontology enrich --all --level L1             # apply batch

Domain taxonomy

Skills are classified into a two-level hierarchy: agent-architecture, education, document-processing, business, knowledge-work, meta, and more. Domains are auto-inferred from skill names when possible.

See docs/ontology-design.md for the full design document.

---

Agent Targets

Built-in targets:

Add custom targets:

neoskills config set targets.my-agent.skill_path /path/to/skills

---

Operating Modes

1. CLI (default) – neoskills runs as a standalone command-line tool
2. Agent-invoked tool – Claude Code or OpenCode calls neoskills programmatically
3. Embedded MCP plugin – neoskills runs inside Claude Code as an MCP server, exposing 12+ tools including ontology operations

Authentication (for Claude-powered features)

neoskills resolves authentication automatically:

1. .env API key – loads from ./, .neoskills/, or ~/.neoskills/.env
2. SDK subscription reuse – works inside Claude Code/Desktop without a key
3. Disabled – non-LLM features work without any key (tap, link, list, ontology, etc.)

---

CLI Reference

Workspace

Taps

Skills

Ontology

Advanced

---

Development

Setup

git clone https://github.com/neolaf2/neoskills
cd neoskills
uv sync --dev

Commands

uv run pytest -v              # run all tests (172 tests)
uv run ruff check src/        # lint
uv run neoskills --help        # run from source

Project structure

src/neoskills/
├── cli/              # Click CLI commands
│   ├── main.py       # Entry point and command registry
│   ├── create_cmd.py # Skill scaffolding
│   ├── ontology_cmd.py # 17 ontology subcommands
│   └── ...           # tap, link, list, doctor, etc.
├── core/             # Cellar, config, checksum, frontmatter, linker
├── ontology/         # Property graph layer (v0.4)
│   ├── models.py     # Enums + dataclasses (SkillNode, OntologyEdge, etc.)
│   ├── graph.py      # SkillGraph -- in-memory property graph
│   ├── loader.py     # Filesystem -> graph
│   ├── writer.py     # Graph -> filesystem (ontology.yaml)
│   ├── engine.py     # High-level API (OntologyEngine)
│   ├── taxonomy.py   # Domain taxonomy + inference
│   ├── lifecycle.py  # State machine transitions
│   ├── versioning.py # Semver operations
│   ├── composition.py # Compose/decompose skills
│   ├── export.py     # Mermaid, DOT, JSON, ASCII tree
│   └── scaffold.py   # Template-based skill creation
├── runtime/          # Agent runtime integrations
│   └── claude/
│       └── plugin.py # MCP plugin (12+ tools)
└── __init__.py
tests/
├── unit/             # 172 tests across 12 test modules
└── integration/      # End-to-end workflow tests
docs/
└── ontology-design.md  # Full ontology design document

Release process

# 1. Bump version in pyproject.toml and src/neoskills/__init__.py
# 2. Build and upload
uv build
uv run twine upload dist/*

# 3. Verify
pip install --upgrade neoskills && neoskills --version

---

License

MIT – see LICENSE

Author

Richard Tong