neoskills 0.3.1

Homebrew-style skill manager for AI coding agents

neoskills

Cross-Agent Skill Bank, Transfer System, and Embedded Skill Substrate

neoskills manages skills as the common denominator across multiple agent ecosystems (Claude Code, OpenCode, OpenClaw). It maintains a canonical, portable master skill bank that you can view in one place, sync to GitHub, and deploy selectively to different agents, instances, and workflows.

Features

• Canonical Skill Bank with LTM/STM memory model and variant support per agent
• Multi-ecosystem discovery - scan Claude Code, OpenCode, and OpenClaw for installed skills
• Bidirectional transfer - import skills into the bank, deploy them to any target
• Symlink-based embedding - zero-copy, reversible projection into agent skill directories
• Web acquisition - import from git repos, zip URLs, or raw file URLs
• Git sync - version control your skill bank and push/pull to GitHub
• Claude-powered enhancement - normalize, audit, generate variants, add docs/tests
• Bundle management - group skills into deployable sets for workflows, teams, or machines
• Plugin mode - runs inside Claude Code as an embedded plugin with agents and commands

Installation

pip install neoskills

Or with uv:

uv add neoskills

Quick Start

# Install from PyPI
pip install neoskills
# or with uv
uv add neoskills

# Initialize workspace
neoskills init

# Discover skills across your agent ecosystems
neoskills scan claude-code-user
neoskills scan opencode-local

# Import skills into the bank
neoskills import from-target claude-code-user --skill skill-discovery
neoskills import from-git https://github.com/your-org/skills-repo

# Deploy to a different agent
neoskills deploy skill skill-discovery --to opencode-local

# Embed bank into an agent via symlinks
neoskills embed --target claude-code-user
neoskills unembed --target claude-code-user

# Sync with GitHub
neoskills sync commit -m "Add new skills"
neoskills sync push

# Enhance with Claude
neoskills enhance audit --skill skill-discovery
neoskills enhance normalize --skill skill-discovery --apply

Architecture

~/.neoskills/
├── LTM/                        # Long-term portable knowledge
│   ├── myMemory/               # User-editable agent memory
│   │   ├── AGENTS.md           # Operating instructions
│   │   ├── SOUL.md             # Persona, boundaries, tone
│   │   ├── TOOLS.md            # Tool notes and conventions
│   │   ├── BOOTSTRAP.md        # First-run ritual
│   │   ├── IDENTITY.md         # Agent name, vibe, emoji
│   │   └── USER.md             # User profile and preferences
│   ├── bank/
│   │   ├── skills/             # Canonical skill bank
│   │   │   └── <skill_id>/
│   │   │       ├── canonical/  # Master copy
│   │   │       ├── variants/   # Agent-specific variants
│   │   │       ├── metadata.yaml
│   │   │       └── provenance.yaml
│   │   ├── plugins/
│   │   └── bundles/
│   ├── mappings/
│   │   ├── targets/            # Deployment target definitions
│   │   └── translators/
│   └── sources/
├── STM/                        # Short-term runtime artifacts
│   ├── sessions/
│   ├── runs/
│   ├── logs/
│   └── scratch/                # Embed backups
├── targets/
├── registry.yaml               # Master skill catalog
├── config.yaml                 # Configuration
└── state.yaml                  # Embed state

Targets

neoskills ships with four built-in targets:

Target	Agent	Discovery Path
claude-code-user	Claude Code	~/.claude/skills
claude-code-plugins	Claude Code	~/.claude/plugins/*/skills
opencode-local	OpenCode	~/.config/opencode/skills
openclaw-custom	OpenClaw	(user-defined)

Add custom targets:

neoskills target add my-server \
  --agent-type claude-code \
  --discovery ~/.claude/skills \
  --install ~/.claude/skills

CLI Reference

Command	Description
neoskills init	Create ~/.neoskills/ workspace
neoskills target list|add	Manage deployment targets
neoskills scan <target>	Discover skills in a target
neoskills import from-target|from-git|from-web	Import skills to bank
neoskills deploy skill|bundle --to <target>	Deploy to a target
neoskills deploy create-bundle	Create a skill bundle
neoskills embed|unembed	Symlink projection into agents
neoskills sync status|commit|push|pull	Git operations on bank
neoskills enhance <op> --skill <id>	Claude-powered enhancement
neoskills validate [--skill <id>]	Validate skills (structure, references)
neoskills install <skill_id>...	One-step bank verify + embed
neoskills agent list|run	List or run autonomous agents
neoskills config set|get|show	Configuration management
neoskills plugin create|validate	Plugin scaffolding and validation

Three Operating Modes

1. External Orchestrator (default) - CLI runs independently, scans/imports/deploys across agents
2. Agent-invoked Tool - Claude Code or OpenCode calls neoskills as a tool
3. Embedded Plugin Mode - neoskills installs itself as a Claude Code plugin, exposing agents, skills, and the /ns command

Authentication

neoskills resolves authentication automatically:

1. .env API key - loads from ./, .neoskills/, or ~/.neoskills/.env
2. SDK subscription reuse - works inside Claude Code/Desktop with no API key
3. Disabled - non-LLM features still work (scan, import, deploy, embed)

Development

# Clone and install
git clone https://github.com/neolaf2/neoskills
cd neoskills
uv sync --dev

# Run tests
uv run pytest -v

# Lint
uv run ruff check src/

# Run locally
uv run neoskills --help

Docker

docker build -t neoskills .
docker run -e ANTHROPIC_API_KEY=... neoskills scan claude-code-user

License

MIT - see LICENSE

Author

Richard Tong