Personalizando tu Workspace con Claude Code: Skills, Comandos y Workflow

Ya tienes Claude Code funcionando en PyCharm. Puedes pedirle que lea archivos, ejecute comandos, genere código. Pero hay un problema: Claude Code vanilla no conoce tu forma de trabajar.

Cada vez que empiezas un proyecto nuevo, tienes que explicarle:

• "Usa pytest para tests, no unittest"
• "Los commits siguen conventional commits"
• "Revisa el código antes de commitear"
• "Documenta con docstrings de Google style"

Es como contratar un desarrollador junior brillante que necesita las mismas instrucciones en cada proyecto. Funciona, pero es como explicarle a tu GPS cada mañana que sí, sigues viviendo en la misma dirección. 🤦‍♂️

Hoy vas a transformar Claude Code en tu copiloto personalizado. Crearás herramientas reutilizables que conocen tu workflow, tus convenciones, tu stack. Una vez configuradas, funcionan en cualquier proyecto.

Al final de este post tendrás:

• Code Reviewer automático - Review en 30 segundos con checklist consistente
• Test & Doc generators - Plantillas listas para adaptar
• Slash commands - /commit genera mensajes, /review lanza el revisor
• CLAUDE.md template - Contexto de proyecto automático

Y lo mejor: configurar esto te lleva 20 minutos. Usarlo te ahorra horas cada semana. ROI del 10000% (aproximadamente, no he hecho las cuentas pero suena convincente 🙄).

Recap Rápido (Si No Vienes del Post 1)

Si vienes del Post 1: Setup y Fundamentos, ya tienes Claude Code instalado y configurado. Si llegaste directo aquí porque "tutorial de skills" sonaba interesante en Google:

• Claude Code es un asistente de IA que vive en PyCharm
• Lee tu código, ejecuta comandos, entiende tu proyecto completo
• Necesitas Claude Pro ($20/mes) para usarlo productivamente
• Instalación: Plugin de PyCharm + autenticación

Si no lo tienes configurado, empieza por el Post 1. Este post asume que ya funciona.

Preview de lo que Construiremos

Vamos a crear 3 tipos de personalizaciones:

1. Skills - Agentes especializados que resuelven tareas complejas
2. Slash commands - Atajos rápidos para acciones comunes
3. CLAUDE.md - Contexto automático de tu proyecto

Todo reutilizable. Configuras una vez, usas en todos tus proyectos.

Empezamos con el más potente: un code reviewer automático.

Tu Primer Custom Skill: Code Reviewer

Por Qué Code Review Automático

Code review es una de esas cosas que sabes que deberías hacer pero... ¿quién tiene tiempo? Especialmente en proyectos personales donde eres el único developer.

El problema no es solo tiempo. Es consistencia. Algunos días revisas todo con lupa. Otros días commiteas directamente porque "es un cambio pequeño" (spoiler: tenía 3 bugs 🐛🐛🐛).

Un code reviewer automatizado te da:

• Checklist consistente (no se olvida de nada, ni siquiera un viernes a las 6pm)
• Segunda opinión instantánea
• Aprendizaje continuo (ve patrones que repites)

Cómo Funcionan los Skills

Un skill es básicamente un agente de IA especializado que vive en .claude/skills/nombre-skill/skill.md.

Estructura simple:

.claude/
└── skills/
    └── code-reviewer/
        └── skill.md    # Todo aquí: instrucciones, checklist, formato

Ese archivo markdown contiene:

• Qué hace el skill
• Cuándo usarlo
• Proceso paso a paso
• Tools que puede usar (Read, Grep, Write)
• Formato del output

Claude Code lo lee y sabe exactamente qué hacer.

Demo: Code Reviewer en Acción

Tienes este código:

def get_user(id):
    query = "SELECT * FROM users WHERE id = " + str(id)
    result = db.execute(query)
    return result[0]

Le pides:

Tú: "Usa code-reviewer para revisar user_service.py"

En 30 segundos obtienes:

# Code Review: user_service.py

## 🔴 Críticos

### SQL Injection Vulnerability (Línea 3)
**Problema:** Concatenación directa en query SQL
**Por qué importa:** Permite inyección SQL
**Solución:**
query = "SELECT * FROM users WHERE id = ?"
result = db.execute(query, (id,))  # Parameterized

### Missing None Check (Línea 4)
**Problema:** `result[0]` falla si no hay resultados
**Solución:** Verificar `if result:` antes de acceder

Review completo con:

• Bugs de seguridad 🔴
• Code smells 🟡
• Mejoras opcionales 🟢
• Aspectos positivos ✅

Instalación

El código completo del skill está en el repositorio de ejemplos.

Copia .claude/skills/code-reviewer/ a tu proyecto y funciona inmediatamente. Puedes personalizarlo (agregar checks de Django, FastAPI, etc.).

Más Skills Listos para Usar

Has visto cómo funciona un skill completo. Ahora dos más que copias y usas en 2 minutos:

Test Writer

Qué hace: Genera tests automáticamente (pytest por defecto).

Uso:

Tú: "Genera tests para calculate_discount()"

Claude Code:
[Analiza función, identifica edge cases, genera suite completa]

Output:

class TestCalculateDiscount:
    def test_senior_discount(self):
        # edad > 65 → 20% descuento

    def test_adult_discount(self):
        # edad 18-65 → 10% descuento

    def test_minor_no_discount(self):
        # edad < 18 → 0% descuento

    def test_edge_case_negative_age(self):
        # pytest.raises(ValueError)

Happy path + edge cases + error handling. Listo.

Personalización: Cambia pytest → unittest en 1 línea del skill.

Doc Generator

Qué hace: Documenta funciones/clases automáticamente (Google style por defecto).

Uso:

Tú: "Documenta la clase UserService"

Claude Code:
[Lee clase, genera docstring completo]

Output:

class UserService:
    """Service for managing user operations.

    Handles user CRUD, authentication, and profile management.
    Integrates with PostgreSQL database.

    Args:
        db: Database connection instance
        cache: Redis cache for sessions

    Examples:
        >>> service = UserService(db)
        >>> user = service.get_user(123)
    """

Docstrings completos con ejemplos. También genera READMEs para módulos.

Personalización: Cambia Google style → NumPy/Sphinx en 1 línea.

---

Los 3 skills están en el repo de ejemplos. Copia, adapta a tu stack (5 minutos), úsalos para siempre.

Slash Commands: Productividad Instantánea

¿Qué son los Slash Commands?

Los slash commands son atajos rápidos que ejecutas escribiendo /nombre en Claude Code. Piensa en ellos como comandos de terminal, pero para tu asistente de IA.

Diferencia con Skills:

Ejemplo:

• Skill: "Usa code-reviewer para analizar este archivo" → Agente lee, analiza, genera report
• Slash command: /commit → Claude genera mensaje de commit → Tú copias y usas

Los slash commands son para cuando necesitas output rápido, no análisis profundo.

Estructura:

Aún más simple que skills:

.claude/
└── commands/
    ├── commit.md
    └── review.md

Cada archivo tiene un prompt simple. Eso es todo.

Comando #1: /commit - Mensajes Conventional Commits

Por qué lo necesitas:

Conventional commits son el estándar (feat:, fix:, docs:, etc.), pero escribirlos bien cada vez es tedioso:

# ¿Cuál de estos usas normalmente?
git commit -m "stuff"           # 😅 Honesto pero inútil
git commit -m "fixed bug"       # 🤷 ¿Que bug?
git commit -m "updated code"    # 🙄 Ya, eso hace un commit

Con /commit:

Tú: "/commit"

Claude Code:
"Veo que modificaste user_service.py (SQL injection fix) y
agregaste tests. ¿Este commit message funciona?

fix: prevent SQL injection in get_user query

- Replace string concatenation with parameterized query
- Add input validation for user_id parameter
- Include test coverage for edge cases

Addresses security vulnerability in user lookup."

Copy-paste. Commit. Listo.

Instalación: Copia de repo de ejemplos.

Comando #2: /review - Code Review Rápido

Diferencia con el skill:

• Skill code-reviewer: Análisis exhaustivo (bugs, seguridad, performance, todo)
• Comando /review: Vista rápida antes de commit ("¿hay algo obviamente mal?")

Uso:

Tú: "/review"

Claude Code:
"Revisión rápida de cambios staged:

✅ No veo bugs obvios
⚠️  Línea 23: Falta type hint en parámetro 'data'
💡 Considera agregar docstring a nueva función

2 segundos. Suficiente para un sanity check antes de push.

Cuándo usar cada uno:

• /review → Antes de commit (quick check)
• code-reviewer skill → Después de feature completa (deep dive)

---

Ambos comandos en el repo. Instala en 30 segundos, usa para siempre.

CLAUDE.md: Contexto Automático de Tu Proyecto

El Problema de la Memoria a Corto Plazo

Has configurado skills increíbles. Tienes slash commands listos. Pero cada vez que abres un proyecto nuevo, Claude Code pregunta:

• "¿Qué framework usas?"
• "¿Cuál es tu estructura de carpetas?"
• "¿Usas pytest o unittest?"
• "¿Dónde están los tests?"

Es como explicarle a un compañero nuevo dónde está todo... en cada proyecto... cada vez (vale, a lo mejor esto si que ha pasado alguna vez, verdad?).

La Solución: CLAUDE.md

CLAUDE.md es un archivo en la raíz de tu proyecto que Claude Code lee automáticamente al abrir. Es el manual de tu proyecto.

Piensa en ello como onboarding documentation, pero para tu IA.

Ubicación:

tu-proyecto/
├── .claude/              # Skills y commands (generales)
├── CLAUDE.md            # ← Contexto de ESTE proyecto
├── src/
└── tests/

Template Estructurado

Aquí está la estructura que funciona para el 90% de proyectos Python:

# Project: [Nombre del Proyecto]

> **Descripción breve:** Qué hace este proyecto en una línea

## Tech Stack

- **Language:** Python 3.12
- **Framework:** FastAPI 0.104
- **Database:** PostgreSQL 15
- **Testing:** pytest + pytest-asyncio
- **Linting:** ruff + mypy

## Project Structure

src/
├── api/          # FastAPI routes
├── services/     # Business logic
├── models/       # SQLAlchemy models
└── utils/        # Helper functions

tests/
├── unit/         # Unit tests
└── integration/  # Integration tests


## Development Commands

# Setup
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
# Run
uvicorn src.main:app --reload

# Test
pytest tests/ -v

# Lint
ruff check .
mypy src/


## Code Conventions

- **Imports:** Absolute imports from `src/`
- **Type hints:** Required for all functions
- **Docstrings:** Google style
- **Line length:** 100 chars (Black default)
- **Async:** Use async/await for I/O operations

## Testing Strategy

- Unit tests for business logic (src/services/)
- Integration tests for API endpoints
- Mocks for external APIs (httpx_mock)
- Fixtures in tests/conftest.py
- Target coverage: >80%

## Database

- Migrations: Alembic
- ORM: SQLAlchemy 2.0 (async)
- Connection: asyncpg driver

## Custom Skills Available

You have access to these project skills:
- `code-reviewer` - Pre-commit code review
- `test-writer` - Generate pytest tests
- `doc-generator` - Auto-document functions

Use them with the Task tool.

## Notes

- API keys in .env (never commit)
- Follow REST conventions for endpoints
- All routes require authentication except /health

Ejemplo Real: Proyecto FastAPI

Supongamos estás trabajando en una API de e-commerce. Tu CLAUDE.md:

# Project: E-Commerce API

> REST API para tienda online con productos, carrito y checkout

## Tech Stack

- Python 3.12 + FastAPI
- PostgreSQL (productos, usuarios)
- Redis (cache, sessions)
- Stripe (pagos)

## Key Directories

- `src/api/products/` - CRUD de productos
- `src/api/cart/` - Carrito de compras
- `src/api/checkout/` - Proceso de pago
- `src/services/payment/` - Integración Stripe

## Important

- Todos los precios en centavos (int, no float)
- Carrito expira a las 24h (Redis TTL)
- Tests de pago usan Stripe test mode

## Custom Skills

- `stripe-tester` - Genera test cases para Stripe
- `api-validator` - Valida OpenAPI schema

Ahora cuando le pidas "Crea endpoint para agregar producto al carrito", Claude Code ya sabe:

• Estructura de carpetas (src/api/cart/)
• Framework (FastAPI)
• Testing (pytest)
• Convención de precios (centavos, int)

Sin preguntar nada.

Bonus: Referencia a Tus Skills

La sección "Custom Skills Available" es clave. Le recuerdas a Claude qué herramientas tiene:

## Custom Skills Available

- `code-reviewer` - Use before commits
- `test-writer` - Generate tests (pytest)
- `doc-generator` - Document with Google docstrings
- `api-designer` - Design REST endpoints (este proyecto)

Así Claude puede sugerir skills proactivamente:

Tú: "Acabé de escribir la función process_payment()"

Claude Code:
"Perfecto. Veo que tienes:
1. test-writer skill disponible - ¿Genero tests?
2. doc-generator skill disponible - ¿Agrego docstring?
¿Cuál prefieres primero?"

Instalación:

Template completo en el repo de ejemplos.

Copia CLAUDE.md.template, renombra a CLAUDE.md, adapta a tu proyecto (5 minutos). Claude Code lo lee automáticamente.

Tu Workflow Optimizado

Tienes skills, comandos y CLAUDE.md configurados. Ahora la pregunta: ¿cómo usas todo esto en tu día a día?

Aquí está un workflow real usando las herramientas que acabas de crear:

Morning Routine: Retomando el Trabajo

Antes (sin personalización):

Tú: "Claude, estaba trabajando en el módulo de pagos"
Claude: "¿Qué framework usas? ¿Dónde están los archivos?"
Tú: *suspiro* "FastAPI, está en src/api/payments/"
Claude: "¿Qué querías hacer exactamente?"

Ahora (con CLAUDE.md):

Tú: "Retomemos el módulo de pagos"
Claude: "Veo que estás en src/api/payments/. Tienes checkout.py
sin terminar (línea 45 está incompleta). ¿Continúo ahí?"

Lee CLAUDE.md → Entiende proyecto → Va directo al grano.

Pro Tip 💡: Puedes usar un fichero específico donde ir guardando el contexto : CONTEXT.md

Durante Desarrollo: Feature Nueva

Escenario: Crear endpoint para procesar reembolsos

Tú: "Crea endpoint POST /refunds para procesar reembolsos Stripe"

Claude Code:
[Lee CLAUDE.md: proyecto usa FastAPI + Stripe]
[Genera endpoint en src/api/refunds/routes.py]
[Sigue convenciones del proyecto automáticamente]

Tú: "Ahora genera tests"

Claude Code:
[Usa test-writer skill]
[Genera tests/integration/test_refunds.py con pytest]
[Incluye mocks de Stripe según notas en CLAUDE.md]

Tú: "Documenta la función"

Claude Code:
[Usa doc-generator skill]
[Agrega docstring Google style según CLAUDE.md]

3 comandos. Feature completa con tests y docs.

Before Commit: Quality Check

Checklist pre-commit:

Tú: "/review"
Claude: "✅ No veo problemas obvios. Listo para commit."

Tú: "Usa code-reviewer para análisis completo"
Claude: [Deep review]
"🟡 Línea 34: Considera agregar try-catch para Stripe API
 🟢 Todo lo demás se ve bien"

[Haces el fix]

Tú: "/commit"
Claude: "feat(refunds): add Stripe refund processing endpoint

- Implement POST /refunds with validation
- Add integration tests with Stripe mocks
- Include error handling for failed refunds

Closes #123"

Copia mensaje → Commit → Push.

Proceso completo en 2 minutos. Sin cambiar de ventana, sin ChatGPT en otra pestaña.

Debugging: WTF Moment 🤨

Escenario: Tests fallan y no sabes por qué

Antes:

Tú: "Los tests fallan"
Claude: "¿Qué tests? ¿Qué error da?"
Tú: *copia 50 líneas de traceback*
Claude: "Parece un problema de..."

Ahora:

Tú: "Tests de refunds fallan"
Claude:
[Lee CLAUDE.md: tests en tests/integration/]
[Lee conftest.py: fixtures disponibles]
[Lee test_refunds.py: código del test]
[Analiza error]

"El problema está en línea 23 del test. Usas fixture 'db_session'
pero según conftest.py se llama 'async_db_session'. Cambia:

def test_refund(db_session):  # ❌
def test_refund(async_db_session):  # ✅

Claude tiene contexto completo sin que se lo des. Lee proyecto, entiende setup, encuentra el issue.

Refactoring: Cambio Grande

Escenario: Mover lógica de payments de routes a services

Tú: "Necesito mover la lógica de pagos a services/"

Claude:
[Lee CLAUDE.md: estructura de carpetas]
[Entiende patrón: routes delgados, services con lógica]

"Plan:
1. Crear src/services/payment_service.py
2. Mover process_payment() de routes
3. Actualizar imports en routes.py
4. Regenerar tests para service layer
¿Procedo?"

Tú: "Sí"

[Ejecuta plan]
[Usa test-writer para nuevos tests]

Claude: "✅ Refactor completo.
Ejecuta: pytest tests/unit/test_payment_service.py"

Refactor coordinado. Sin romper nada.

El Patrón

Todo tu workflow ahora sigue este ciclo:

1. Desarrollar → Claude conoce tu proyecto (CLAUDE.md)
2. Validar → Skills automatizan review/tests/docs
3. Commit → Slash commands generan mensajes
4. Repetir → Sin fricciones, sin context switching

Resultado: Más tiempo creando, menos tiempo explicando contexto.

Conclusión y Próximos Pasos

Has transformado Claude Code de asistente genérico a copiloto personalizado.

Herramientas configuradas:

• 3 skills reutilizables - Code reviewer, test writer, doc generator
• 2 slash commands - /commit y /review para productividad instantánea
• CLAUDE.md template - Contexto automático en cada proyecto
• Workflow optimizado - De idea a commit sin fricciones

El Verdadero Valor

No es solo automatización. Es consistencia.

• Code reviews con el mismo estándar (viernes 6pm = lunes 9am)
• Tests que cubren casos que normalmente olvidarías
• Commits con mensajes profesionales siempre
• Documentación que no postpones "para después"

Configuraste esto una vez. Lo usas en todos tus proyectos. Para siempre.

Recursos Creados

Todo el código está en el repositorio de ejemplos:

Blog-Code-Examples/
└── .claude/
    ├── skills/
    │   ├── code-reviewer/
    │   ├── test-writer/
    │   └── doc-generator/
    ├── commands/
    │   ├── commit.md
    │   └── review.md
    └── templates/
        └── CLAUDE.md.template

Instalación rápida:

# Clona el repo
git clone https://github.com/fparis-sp/Blog-Code-Examples.git

# Copia skills a tu proyecto
cp -r Blog-Code-Examples/.claude tu-proyecto/

# Adapta CLAUDE.md
cp Blog-Code-Examples/.claude/templates/CLAUDE.md.template tu-proyecto/CLAUDE.md
# Edita CLAUDE.md con tu stack

5 minutos. Listo para usar.

Personalización Avanzada

Estos skills son punto de partida. Adáptalos a tu stack:

• ¿Usas Django? Agrega checks específicos de ORM en code-reviewer
• ¿FastAPI? Crea skill para diseño de endpoints REST
• ¿React? Template para componentes con tests de Jest
• ¿Docker? Skill que genera Dockerfile optimizado

El patrón es el mismo. Cambia el checklist según tu tecnología.

Próximo Paso: Proyecto Real

En el Post 3 de esta serie, construiremos una Pokédex interactiva con Flask desde cero, usando todos estos skills trabajando en equipo. (Si no sabes Flask, no te preocupes)

Verás:

• writing-plans + executing-plans en acción (plan completo → ejecución por batches)
• Skills orquestándose automáticamente (code-reviewer, test-writer, doc-generator)
• Workflow completo: idea → plan → código → tests → docs → proyecto funcionando
• Review checkpoints después de cada batch (mantienes control total)

El resultado: una web app visual funcionando en localhost:5000 con búsqueda en vivo, stats animados, comparador de Pokémon y versiones shiny. Todo en menos de 2 horas vs 7 horas manual.

De "configurar skills uno a uno" a "orquestar todos juntos en proyecto real".

¿Y Después? Post 4: Multi-Agentes en Proyecto Real

Una vez que tengas el Pokédex funcionando (Post 3), el Post 4 final de la serie mostrará cómo mejorar un proyecto existente con agentes especializados de IA.

Tomaremos tu Pokédex y añadiremos:

• Agent estratega: Analiza type matchups y recomienda counters óptimos
• Agent team builder: Sugiere equipos balanceados según rival
• Agent conversacional: Responde preguntas sobre Pokémon en lenguaje natural

Un solo endpoint nuevo (/ask) conecta tres agentes trabajando juntos. Verás cómo transformar un proyecto "normal" en uno potenciado por IA, sin reescribir todo desde cero.

Arquitectura multi-agente aplicada a tu proyecto real.

Una Última Cosa

Si vienes del Post 1: Setup y Fundamentos, has avanzado en la transformación:

• Post 1: Claude Code funcionando ✅
• Post 2: Claude Code personalizado ✅
• Post 3: Claude Code en proyecto real (próximamente)
• Post 4: Claude Code añade IA a tu proyecto. (próximamente)

Tu workspace ahora es único. Tus herramientas. Tu workflow. Tu productividad.

---

💼 ¿Quieres llevar esto al siguiente nivel?

Estos posts te dan los fundamentos para trabajar productivamente con Claude Code. Si te interesa profundizar en proyectos production-ready (RAG systems, APIs completas, dashboards interactivos), estate atento al blog.

Próximamente compartiré casos reales del proyecto franciscoparis.com: cómo construí el AI Papers Hub, el sistema de gamificación con D3.js, y la arquitectura Django + Next.js.

Recursos

Código

• Repositorio de ejemplos - Skills, commands, templates

Documentación

• Claude Code - JetBrains IDEs
• Task Tool Documentation

Serie Claude Code

• Post 1: Setup y Fundamentos
• Post 2: Personalizando tu Workspace (este post)
• Post 3: Tu Primer Proyecto Completo (próximamente)

Posts Relacionados

• Introducción a Agentes de IA
• Construyendo Sistemas RAG con LangChain

---

¿Tienes preguntas sobre Claude Code? Contáctame o conectemos en LinkedIn.