🚀 Skill Fleet

A local-first platform for creating, validating, and curating AI agent skills as standards-compliant artifacts.

Skill Fleet transforms natural language descriptions into production-ready agent skills using an intelligent three-phase workflow: Understanding → Generation → Validation. Built on DSPy for reliable, optimizable LLM programs.

# Create a skill in minutes
uv run skill-fleet chat "Create a React hooks mastery skill for intermediate developers"

✨ Why Skill Fleet?

Traditional prompt engineering creates fragile, unversioned prompts that break when models change. Skill Fleet creates structured, validated, reusable artifacts that agentskills.io-compliant agents can consume.

Key Differentiators

🚀 Quick Start

Prerequisites

• Python 3.12+
• uv package manager
• Git
• API Key: Google (Gemini) or LiteLLM proxy

Installation

# Clone and setup
git clone https://github.com/qredence/skill-fleet.git
cd skill-fleet
uv sync --group dev

# Configure environment
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY or LITELLM credentials

First Skill Creation

# Start the API server
uv run skill-fleet serve

# In another terminal, create a skill interactively
uv run skill-fleet chat "Create a skill for Python decorators"

# Or create non-interactively with auto-approval
uv run skill-fleet create "Build a React testing skill" --auto-approve

# Validate the generated skill
uv run skill-fleet validate skills/_drafts/<job_id>

# Promote to taxonomy when ready
uv run skill-fleet promote <job_id>

🏗️ Architecture

Skill Fleet uses a three-phase workflow powered by DSPy:

User Request
    ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 1: Understanding                                 │
│  - Extract requirements                                 │
│  - Analyze intent                                       │
│  - Build execution plan                                 │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 2: Generation                                    │
│  - Create SKILL.md with YAML frontmatter                │
│  - Generate code examples                               │
│  - Apply category-specific templates                    │
└─────────────────────────────────────────────────────────┘
    ↓
┌─────────────────────────────────────────────────────────┐
│  Phase 3: Validation                                    │
│  - Structure validation                                 │
│  - Compliance checking                                  │
│  - Quality assessment (Best-of-N)                       │
└─────────────────────────────────────────────────────────┘
    ↓
Draft Ready for Review → Promote to Taxonomy

Draft-First Workflow

1. Draft Phase: Skills are generated into skills/_drafts/<job_id>/
2. Review Phase: Human-in-the-loop (HITL) for feedback and refinement
3. Promotion Phase: Validated skills moved to stable taxonomy paths

📋 CLI Reference

Core Commands

Server Options

# Development mode with auto-reload
uv run skill-fleet serve --reload

# Skip database initialization
uv run skill-fleet serve --skip-db-init

# Custom port
uv run skill-fleet serve --port 8080

Validation Options

# Validate with JSON output for scripting
uv run skill-fleet validate ./my-skill --json

# Disable LLM-backed validation (rule-based only)
uv run skill-fleet validate ./my-skill --no-llm

# Override API server URL
uv run skill-fleet validate ./my-skill --api-url http://localhost:8000

🔧 Configuration

Environment Variables

Create .env file (copy from .env.example):

* Choose either Google API key OR LiteLLM credentials.

Note: LITELLM_BASE_URL must point to the LiteLLM proxy root (or optional /v1). Provider endpoints like .../generateContent are invalid and will error.

Development vs Production

Development Mode (SKILL_FLEET_ENV=development):

• SQLite fallback (no DATABASE_URL required)
• CORS allows *
• Debug logging
• Auto-reload enabled

Production Mode (SKILL_FLEET_ENV=production):

• PostgreSQL required
• Explicit CORS origins required
• Structured logging
• Security headers enabled

🌐 API Reference

When the server is running, access interactive documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Key Endpoints

Streaming API

For real-time progress updates:

curl -X POST http://localhost:8000/api/v1/skills/stream \
  -H "Content-Type: application/json" \
  -d '{
    "task_description": "Create a Python asyncio skill",
    "user_id": "developer-1",
    "enable_hitl": true
  }'

Returns Server-Sent Events (SSE) with:

• Phase transitions (Understanding → Generation → Validation)
• Real-time reasoning and thoughts
• Progress updates
• HITL suspension points

🧪 Development

Setup

# Install dependencies
uv sync --group dev

# Run linting and formatting
uv run ruff check --fix .
uv run ruff format .

# Run type checker
uv run ty check

# Run tests
uv run pytest

# Run specific test
uv run pytest tests/unit/test_async_utils.py -v

Pre-commit Hooks

# Install hooks
uv run pre-commit install

# Run manually
uv run pre-commit run --all-files

Project Structure

src/skill_fleet/
├── api/                    # FastAPI application
│   ├── v1/                 # API endpoints (skills, jobs, HITL)
│   └── services/           # Business logic layer
├── cli/                    # Typer CLI application
├── core/                   # Core business logic
│   ├── modules/            # DSPy modules (generation, validation)
│   ├── signatures/         # DSPy signatures
│   └── workflows/          # Workflow orchestration
├── taxonomy/               # Taxonomy management
└── infrastructure/         # Database, monitoring, tracing

📚 Documentation

🤝 Contributing

We welcome contributions! Please see docs/explanation/development/contributing.md for guidelines.

Quick Contribution Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (uv run pre-commit run --all-files)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

Apache License 2.0. See LICENSE for details.

🔗 Related Projects

• DSPy - The framework powering our LLM programs
• agentskills.io - The skill standard we implement
• LiteLLM - Proxy for multiple LLM providers

Version: 0.3.6 Status: Alpha Last Updated: 2026-02-03

Built with ❤️ by the Qredence team