Guía de Agent Skills

Esta guía documenta los Agent Skills disponibles en el ambiente de desarrollo y cómo usarlos desde VibeKanban con OpenCode.

¿Qué son los Agent Skills?

Los Agent Skills son módulos de conocimiento reutilizables que guían a los agentes de IA (como OpenCode) para realizar tareas específicas siguiendo las convenciones y mejores prácticas del proyecto.

Cada skill contiene:

Instrucciones detalladas de cómo realizar la tarea
Templates de código listos para usar
Ejemplos de implementación
Triggers (palabras clave) que activan el skill

Skills Disponibles

Skill	Descripción	Triggers
`fastapi-endpoint`	Crea endpoints FastAPI con Pydantic v2, SQLModel y tests	"nuevo endpoint", "crear ruta", "endpoint CRUD"
`pydantic-model`	Define modelos de datos con Pydantic v2	"crear modelo", "nuevo schema", "data model"
`sqlmodel-crud`	Implementa operaciones CRUD con patrón Repository	"crear CRUD", "repository pattern", "database operations"
`reflex-component`	Crea componentes UI con Reflex y Tailwind	"nuevo componente", "crear formulario", "componente UI"
`pytest-test`	Genera tests con pytest	"crear test", "unit test", "integration test"
`security-headers`	Revisa seguridad antes de merge	"security review", "pre-merge check"

Ubicación de los Skills

Los skills están ubicados en el directorio skills/ del proyecto:

sdd-dev/
└── skills/
    ├── fastapi-endpoint/
    │   ├── SKILL.md           # Instrucciones principales
    │   ├── instructions.md    # Instrucciones detalladas
    │   ├── examples/          # Ejemplos de código
    │   └── scripts/           # Scripts de validación
    ├── pydantic-model/
    │   ├── SKILL.md
    │   └── examples/
    ├── sqlmodel-crud/
    │   ├── SKILL.md
    │   └── templates/
    ├── reflex-component/
    │   ├── SKILL.md
    │   └── templates/
    ├── pytest-test/
    │   ├── SKILL.md
    │   └── templates/
    └── security-headers/
        ├── SKILL.md
        └── checklist.md

Cómo Usar los Skills desde VibeKanban

Método 1: Mencionar el Skill en la Descripción de la Tarea

Al crear una tarea en VibeKanban, menciona el skill que quieres usar:

## Tarea: Crear endpoint de usuarios

Usa el skill `fastapi-endpoint` para crear un endpoint CRUD de usuarios.

### Requisitos:
- GET /api/users - Listar usuarios
- POST /api/users - Crear usuario
- GET /api/users/{id} - Obtener usuario
- PUT /api/users/{id} - Actualizar usuario
- DELETE /api/users/{id} - Eliminar usuario

Método 2: Usar Palabras Clave (Triggers)

OpenCode detecta automáticamente los triggers y aplica el skill correspondiente:

## Tarea: Nuevo endpoint de productos

Necesito crear un nuevo endpoint CRUD para gestionar productos.
El endpoint debe incluir autenticación y tests.

Las palabras "nuevo endpoint" y "CRUD" activarán automáticamente el skill fastapi-endpoint.

Método 3: Referenciar el Archivo SKILL.md

Para instrucciones más específicas, puedes referenciar el archivo directamente:

## Tarea: Implementar modelo de Usuario

Sigue las instrucciones en `skills/pydantic-model/SKILL.md` para crear el modelo.

### Campos requeridos:
- id: UUID
- email: str (único)
- name: str
- created_at: datetime

Detalle de Cada Skill

1. FastAPI Endpoint (`fastapi-endpoint`)

Propósito: Crear endpoints de API RESTful siguiendo las convenciones del proyecto.

Convenciones obligatorias:

Usar Annotated[...] para dependencias
Especificar response_model y status_code
Usar Depends() para auth, db, y otras dependencias
Incluir docstrings con descripción de la operación

Ejemplo de uso en VibeKanban:

## Crear endpoint de autenticación

Usa el skill fastapi-endpoint para crear:
- POST /api/auth/login - Login con email/password
- POST /api/auth/register - Registro de usuario
- POST /api/auth/logout - Cerrar sesión
- GET /api/auth/me - Obtener usuario actual

Incluir validación de datos y manejo de errores.

Archivos que genera:

backend/api/endpoints/{nombre}.py - Endpoint
backend/schemas/{nombre}.py - Schemas Pydantic
tests/api/test_{nombre}.py - Tests

2. Pydantic Model (`pydantic-model`)

Propósito: Definir modelos de datos con validación.

Estructura de modelos:

# Base (campos compartidos)
class UserBase(BaseModel):
    email: EmailStr
    name: str

# Create (para POST)
class UserCreate(UserBase):
    password: str

# Update (para PUT/PATCH)
class UserUpdate(BaseModel):
    email: EmailStr | None = None
    name: str | None = None

# Response (para respuestas)
class UserResponse(UserBase):
    id: UUID
    created_at: datetime

Ejemplo de uso en VibeKanban:

## Crear modelo de Producto

Usa el skill pydantic-model para definir:
- ProductBase: name, description, price, category_id
- ProductCreate: hereda de Base
- ProductUpdate: todos los campos opcionales
- ProductResponse: incluye id, created_at, updated_at

3. SQLModel CRUD (`sqlmodel-crud`)

Propósito: Implementar operaciones de base de datos con patrón Repository.

Patrón Repository:

class UserRepository:
    def __init__(self, session: Session):
        self.session = session
    
    async def create(self, data: UserCreate) -> User:
        ...
    
    async def get_by_id(self, id: UUID) -> User | None:
        ...
    
    async def get_all(self, skip: int = 0, limit: int = 100) -> list[User]:
        ...
    
    async def update(self, id: UUID, data: UserUpdate) -> User:
        ...
    
    async def delete(self, id: UUID) -> bool:
        ...

Ejemplo de uso en VibeKanban:

## Implementar CRUD de Categorías

Usa el skill sqlmodel-crud para crear:
- Modelo Category con SQLModel
- CategoryRepository con operaciones CRUD
- Manejo de relaciones con Product

4. Reflex Component (`reflex-component`)

Propósito: Crear componentes UI reutilizables.

Estructura del componente:

import reflex as rx

def button(
    text: str,
    variant: str = "primary",
    on_click: callable = None,
    disabled: bool = False,
) -> rx.Component:
    """Botón reutilizable con variantes."""
    return rx.button(
        text,
        class_name=f"btn btn-{variant}",
        on_click=on_click,
        disabled=disabled,
    )

Ejemplo de uso en VibeKanban:

## Crear componente de Card de Producto

Usa el skill reflex-component para crear:
- ProductCard: muestra imagen, nombre, precio, botón de compra
- Variantes: default, featured, compact
- Responsive design para móvil y desktop

5. Pytest Test (`pytest-test`)

Propósito: Generar tests automatizados.

Estructura de tests:

import pytest
from httpx import AsyncClient

class TestUserEndpoints:
    @pytest.fixture
    async def user_data(self):
        return {"email": "test@example.com", "name": "Test User"}
    
    async def test_create_user(self, client: AsyncClient, user_data):
        response = await client.post("/api/users", json=user_data)
        assert response.status_code == 201
        assert response.json()["email"] == user_data["email"]

Ejemplo de uso en VibeKanban:

## Crear tests para endpoint de productos

Usa el skill pytest-test para crear:
- Tests de creación, lectura, actualización, eliminación
- Tests de validación de datos
- Tests de autenticación
- Cobertura mínima: 80%

6. Security Headers (`security-headers`)

Propósito: Verificar seguridad antes de merge.

Checklist de seguridad:

CORS configurado correctamente
Headers de seguridad (CSP, X-Frame-Options, etc.)
Rate limiting implementado
Validación de entrada en todos los endpoints
Secrets en variables de entorno
SQL injection prevenido (uso de ORM)
XSS prevenido (escape de output)

Ejemplo de uso en VibeKanban:

## Security Review antes de release

Usa el skill security-headers para:
- Revisar todos los endpoints de la API
- Verificar configuración de CORS
- Validar manejo de autenticación
- Generar reporte de seguridad

Crear Nuevos Skills

Puedes crear tus propios skills siguiendo esta estructura:

skills/mi-nuevo-skill/
├── SKILL.md           # Archivo principal (obligatorio)
├── instructions.md    # Instrucciones detalladas (opcional)
├── examples/          # Ejemplos de código (opcional)
├── templates/         # Templates reutilizables (opcional)
└── scripts/           # Scripts de validación (opcional)

Formato de SKILL.md:

---
name: mi-nuevo-skill
description: Descripción breve del skill
triggers:
  - "palabra clave 1"
  - "palabra clave 2"
metadata:
  version: "1.0"
  author: "Tu nombre"
  stack: ["python", "fastapi"]
---

# Nombre del Skill

## Cuándo usar esta skill

Describe cuándo debe usarse este skill.

## Instrucciones

Paso a paso de cómo realizar la tarea.

## Ejemplos

Código de ejemplo.

Integración con AGENTS.md

Los skills se integran con los agentes definidos en AGENTS.md. Cada agente tiene acceso a skills específicos según su rol:

Agente	Skills Disponibles
`backend-dev`	fastapi-endpoint, pydantic-model, sqlmodel-crud, pytest-test
`frontend-dev`	reflex-component, pytest-test
`api-dev`	fastapi-endpoint, pydantic-model, security-headers
`qa-engineer`	pytest-test, security-headers
`devsecops`	security-headers

Verificar Skills Instalados

Para ver los skills disponibles en tu ambiente:

# Listar todos los skills
ls -la skills/

# Ver el contenido de un skill específico
cat skills/fastapi-endpoint/SKILL.md

# Buscar skills por palabra clave
grep -r "endpoint" skills/*/SKILL.md

Dentro del contenedor Docker:

docker compose exec vibekanban ls -la /app/config/skills/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Guía de Agent Skills

¿Qué son los Agent Skills?

Skills Disponibles

Ubicación de los Skills

Cómo Usar los Skills desde VibeKanban

Método 1: Mencionar el Skill en la Descripción de la Tarea

Método 2: Usar Palabras Clave (Triggers)

Método 3: Referenciar el Archivo SKILL.md

Detalle de Cada Skill

1. FastAPI Endpoint (`fastapi-endpoint`)

2. Pydantic Model (`pydantic-model`)

3. SQLModel CRUD (`sqlmodel-crud`)

4. Reflex Component (`reflex-component`)

5. Pytest Test (`pytest-test`)

6. Security Headers (`security-headers`)

Crear Nuevos Skills

Integración con AGENTS.md

Verificar Skills Instalados

FilesExpand file tree

AGENT_SKILLS_GUIDE.md

Latest commit

History

AGENT_SKILLS_GUIDE.md

File metadata and controls

Guía de Agent Skills

¿Qué son los Agent Skills?

Skills Disponibles

Ubicación de los Skills

Cómo Usar los Skills desde VibeKanban

Método 1: Mencionar el Skill en la Descripción de la Tarea

Método 2: Usar Palabras Clave (Triggers)

Método 3: Referenciar el Archivo SKILL.md

Detalle de Cada Skill

1. FastAPI Endpoint (fastapi-endpoint)

2. Pydantic Model (pydantic-model)

3. SQLModel CRUD (sqlmodel-crud)

4. Reflex Component (reflex-component)

5. Pytest Test (pytest-test)

6. Security Headers (security-headers)

Crear Nuevos Skills

Integración con AGENTS.md

Verificar Skills Instalados

1. FastAPI Endpoint (`fastapi-endpoint`)

2. Pydantic Model (`pydantic-model`)

3. SQLModel CRUD (`sqlmodel-crud`)

4. Reflex Component (`reflex-component`)

5. Pytest Test (`pytest-test`)

6. Security Headers (`security-headers`)