skill-fleet 0.3.7

Hierarchical skills taxonomy + DSPy workflow prototype

🚀 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

Feature	Traditional Prompts	Skill Fleet
Creation	Manual, trial-and-error	AI-assisted, structured workflow
Validation	Ad-hoc testing	Multi-phase validation with quality gates
Format	Plain text	agentskills.io compliant SKILL.md
Dependencies	Implicit	Explicitly declared and validated
Versioning	None	Git-tracked with promotion workflow
Discovery	None	Hierarchical taxonomy with search

---

🚀 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

Command	Description	Example
serve	Start FastAPI server	uv run skill-fleet serve --reload
dev	Start server + TUI	uv run skill-fleet dev
chat	Interactive skill creation	uv run skill-fleet chat "Create..."
create	Non-interactive creation	uv run skill-fleet create "..." --auto-approve
validate	Validate skill directory via API	uv run skill-fleet validate skills/_drafts/<job_id>/<skill-name>
promote	Promote draft to taxonomy	uv run skill-fleet promote job_123
generate-xml	Export skills as XML via API	uv run skill-fleet generate-xml
analytics	Show usage analytics via API	uv run skill-fleet analytics --user-id all

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

Variable	Required	Description
GOOGLE_API_KEY	Yes*	Gemini API key (or use LiteLLM)
LITELLM_API_KEY	Yes*	LiteLLM proxy API key
LITELLM_BASE_URL	With LiteLLM	LiteLLM proxy root (e.g. http://localhost:4000)
DATABASE_URL	Production	PostgreSQL connection string
SKILL_FLEET_ENV	No	development (default) or production
SKILL_FLEET_CORS_ORIGINS	Production	Comma-separated allowed origins
SKILL_FLEET_API_URL	CLI	API base URL for API-first CLI commands
SKILL_FLEET_USER_ID	CLI	Default user id for CLI context

* 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

Endpoint	Method	Description
/health	GET	Health check
/api/v1/skills	POST	Create skill (returns job ID)
/api/v1/skills/validate	POST	Validate by taxonomy-relative skill path
/api/v1/skills/{id}	GET	Get skill by ID
/api/v1/skills/{id}/validate	POST	Validate existing skill
/api/v1/jobs/{id}	GET	Get job status and results
/api/v1/taxonomy	GET	List taxonomy categories
/api/v1/taxonomy/xml	GET	Export <available_skills> XML
/api/v1/analytics	GET	Usage analytics
/api/v1/analytics/recommendations	GET	Personalized recommendations
/api/v1/hitl/responses	POST	Submit HITL response

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

Document	Description
docs/README.md	Documentation index and navigation
docs/tutorials/getting-started.md	Step-by-step onboarding
docs/how-to-guides/create-a-skill.md	End-to-end creation guide
docs/how-to-guides/validate-a-skill.md	Validation details
docs/reference/api/endpoints.md	Complete API reference
AGENTS.md	Development workflow guide
SECURITY.md	Security policy

---

🤝 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