Pico-Skills

Claude Code and OpenAI Codex skills for the pico-boot ecosystem.

AI-assisted code generation following pico framework patterns and best practices.

This repo is one third of the ecosystem's built-for-the-AI-era story: the conventions live in each module's AGENTS.md/CLAUDE.md, pico-initializer scaffolds projects that carry them, and these skills teach your coding assistant the whole API surface — so it generates code that fits the framework instead of fighting it.

Platform Compatibility

Pico-Skills follows the Agent Skills standard and supports multiple AI coding agents:

Platform	Skills directory	Status
Claude Code	`.claude/skills/`	Canonical source
OpenAI Codex	`.agents/skills/`	Symlinks to `.claude/skills/`

The .agents/skills/ directory contains symlinks to the canonical .claude/skills/ files, so both platforms always use the same skill definitions.

Available Skills

User-invocable (slash commands)

Command	Package	Description
`/add-component`	pico-ioc	Add components, factories, interceptors, event subscribers, settings
`/add-repository`	pico-sqlalchemy	Add SQLAlchemy entities and repositories with transactions
`/add-controller`	pico-fastapi	Add FastAPI controllers with route decorators
`/add-celery-task`	pico-celery	Add Celery worker tasks and client senders
`/add-validation`	pico-pydantic	Add Pydantic validation to component methods
`/add-auth`	pico-client-auth	Add JWT authentication, role-based access control, custom role resolvers
`/add-server-auth`	pico-server-auth	Add embedded auth server with JWT issuance, wallet login, JWKS
`/add-actuator`	pico-actuator	Add health/info/metrics endpoints and HealthIndicator components
`/add-app`	pico-boot	Scaffold a new pico-boot application
`/init-project`	pico-initializer	Generate a full project with selected modules via pico-initializer CLI
`/add-tests`	all	Generate tests for any pico component

Auto-loaded by Claude (background knowledge)

Skill	Description
`pico-conventions`	API reference and patterns for all pico-* packages. Loaded automatically when Claude detects pico framework usage.

Installation

All skills (recommended)

curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash

By default, skills are installed for both Claude Code (.claude/skills/) and OpenAI Codex (.agents/skills/).

Platform-specific installation

# Claude Code only
curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- --claude

# OpenAI Codex only
curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- --codex

Only the packages you use

curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- sqlalchemy fastapi

Base skills (pico-conventions, add-component, add-tests) are always included.

Available packages

Package	Skill installed
`ioc`	`add-component` (included by default)
`boot`	`add-app`
`fastapi`	`add-controller`
`sqlalchemy`	`add-repository`
`celery`	`add-celery-task`
`pydantic`	`add-validation`
`auth`	`add-auth`
`server-auth`	`add-server-auth`
`actuator`	`add-actuator`

User-level (all projects)

cd ~ && curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash

Usage

/add-component UserService
/add-repository Product
/add-controller /api/orders
/add-celery-task send_notification
/add-validation UserService
/add-auth DatabaseRoleResolver
/add-app my-app
/add-tests UserService

Skill Structure

Each skill follows the Agent Skills standard:

pico-skills/
├── .claude/skills/                # Canonical source (Claude Code)
│   ├── add-component/SKILL.md
│   ├── add-repository/SKILL.md
│   ├── add-controller/SKILL.md
│   ├── add-celery-task/SKILL.md
│   ├── add-validation/SKILL.md
│   ├── add-auth/SKILL.md
│   ├── add-app/SKILL.md
│   ├── add-tests/SKILL.md
│   └── pico-conventions/SKILL.md
├── .agents/skills/                # Symlinks for Codex
│   ├── add-component/SKILL.md  ../../.claude/skills/add-component/SKILL.md
│   ├── add-auth/SKILL.md  ../../.claude/skills/add-auth/SKILL.md
│   ├── add-repository/SKILL.md  ...
│   └── ...
├── install.sh
└── README.md

Pico Ecosystem Packages

Package	PyPI	Description
pico-ioc		IoC container (foundation)
pico-boot		Orchestration & plugin discovery
pico-fastapi		FastAPI integration
pico-sqlalchemy		SQLAlchemy + transactions
pico-celery		Celery task integration
pico-pydantic		Pydantic validation AOP
pico-client-auth		JWT authentication client
pico-server-auth		Embeddable auth server (JWT, wallet, JWKS)
pico-actuator		Health, info and metrics endpoints
pico-resilience		Retry, circuit breaker and timeout AOP
pico-caching		Method result caching
pico-otel		OpenTelemetry tracing and metrics
pico-scheduling		Interval and cron scheduled methods
pico-httpx		Declarative HTTP clients
pico-data-redis		Redis client and distributed cache backend
pico-rabbitmq		RabbitMQ pub-sub
pico-kafka		Kafka producers and consumers
pico-testing		Pytest plugin: isolated containers and fixtures