skillvault 0.1.2

Agent Skill Management System with self-growth capabilities

Skill Manager

Agent Skill Management System with self-growth capabilities.

Published on PyPI: https://pypi.org/project/skillvault/

Features

• Skill Storage: SQLite + sqlite-vec for local storage with vector search
• Semantic Query: ANN retrieval + dependency expansion + token budget cropping
• Self-Growth: Automatically extract knowledge from conversations and tasks
• Human-in-the-Loop: Review queue for approving/rejecting draft skills
• Permission Separation: Agent code can only write drafts, humans control canonical
• CLI Tool: Command-line interface for skill management (optional)

Installation

# Core (SQLite storage + vector search)
pip install skillvault

# With OpenAI embedding support
pip install skillvault[openai]

# With CLI tool
pip install skillvault[cli]

# Everything
pip install skillvault[openai,cli]

Quick Start

import json
from openai import OpenAI
from skillvault import SkillManager
from skillvault.models import Skill, Chunk

client = OpenAI()

# embed_fn: text -> list[float] (1536 dimensions for text-embedding-3-small)
def embed(text: str) -> list[float]:
    resp = client.embeddings.create(model="text-embedding-3-small", input=[text])
    return resp.data[0].embedding

sm = SkillManager("skills.db", embed_fn=embed)

# Register a skill
skill = Skill(
    id="frontend-react",
    name="Frontend React",
    chunks=[
        Chunk(
            id="frontend-react::hooks",
            skill_id="frontend-react",
            section="React Hooks",
            content="## useEffect\n\nUse useEffect for side effects...",
            tokens=50,
        )
    ]
)
sm.register(skill)

# Query skills
context = sm.query("React hooks best practices", budget=2000)
print(context)

Self-Growth (Extract knowledge from conversations)

import json
from openai import OpenAI
from skillvault import SkillManager

client = OpenAI()

def embed(text: str) -> list[float]:
    resp = client.embeddings.create(model="text-embedding-3-small", input=[text])
    return resp.data[0].embedding

# llm_fn: text -> dict (analyze context for reusable knowledge)
def extract_knowledge(text: str) -> dict:
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"""Analyze this conversation and extract reusable knowledge.

{text}

Return JSON:
{{
    "has_knowledge": true/false,
    "title": "short title",
    "playbook": "step-by-step instructions in markdown",
    "examples": "code examples in markdown",
    "when_to_use": "specific scenarios",
    "dependencies": ["related-skill-id"]
}}"""}],
        response_format={"type": "json_object"},
    )
    return json.loads(resp.choices[0].message.content)

sm = SkillManager("skills.db", embed_fn=embed, llm_fn=extract_knowledge)

# Extract from conversation (returns draft_id or None)
draft_id = sm.extract([
    {"role": "user", "content": "How do I handle errors in async Python?"},
    {"role": "assistant", "content": "Use try/except with asyncio.gather..."},
])

# Review and approve
if draft_id:
    pending = sm.review_queue()
    sm.approve(draft_id)

Agent Mode (Restricted permissions)

from skillvault import SkillManager

# Same embed_fn as above
sm = SkillManager("skills.db", embed_fn=embed, mode="agent")

sm.query("...")           # OK - reads canonical skills only
sm.extract(messages)      # OK - creates drafts
sm.register(skill)        # raises PermissionError
sm.approve(draft_id)      # raises PermissionError

CLI Usage

Requires pip install skillvault[cli].

# List skills
python -m skillvault.cli list

# Review queue
python -m skillvault.cli review-queue

# Approve/reject
python -m skillvault.cli approve draft::skill-id
python -m skillvault.cli reject draft::skill-id --reason "Not useful"

# Export/Import
python -m skillvault.cli export frontend-react react.json
python -m skillvault.cli import react.json

# Statistics
python -m skillvault.cli stats

Architecture

SkillManager (one class)
    │
    ├── query(text, budget)        → Search + assemble context
    ├── register(skill)            → Save canonical skill
    ├── extract(context)           → LLM extraction → draft
    ├── approve/reject(skill_id)   → Review workflow
    └── export/import              → JSON serialization
    │
    ├── storage.py    (SQLite + sqlite-vec)
    ├── query.py      (embed + ANN + budget)
    └── growth.py     (LLM analysis + auto-promote)

Development

# Install in dev mode
pip install -e ".[dev,openai,cli]"

# Run tests
pytest

# Format & lint
black src/ tests/
ruff check src/ tests/

License

MIT