# Skill Builder > Crea nuevas Skills de Claude Code con frontmatter YAML correcto, estructura de divulgación progresiva y organización completa de directorios. Fuente: https://skillsagentes.com/skills/ruvnet/ruflo/skill-builder Markdown: https://skillsagentes.com/skills/ruvnet/ruflo/skill-builder.md Repositorio: https://github.com/ruvnet/ruflo Autor: ruvnet Licencia: MIT Actualizado: hace 6 meses Coste de contexto: 67 tok instalada, 5.5k tok al activarse, 5.5k tok con todos los archivos del bundle Bundle: 1 archivo, 21 KB Permisos que pide: ninguno declarado ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add ruvnet/ruflo --skill skill-builder --agent claude-code # Cursor npx -y skills add ruvnet/ruflo --skill skill-builder --agent cursor # Codex npx -y skills add ruvnet/ruflo --skill skill-builder --agent codex # Gemini CLI npx -y skills add ruvnet/ruflo --skill skill-builder --agent gemini # Windsurf npx -y skills add ruvnet/ruflo --skill skill-builder --agent windsurf # Cline npx -y skills add ruvnet/ruflo --skill skill-builder --agent cline ``` ## Qué hace - Guía la creación de Skills de Claude Code con frontmatter YAML correcto (name y description). - Explica la arquitectura de divulgación progresiva en 3 niveles: metadata, cuerpo del SKILL.md y archivos referenciados. - Provee plantillas (básica, intermedia, avanzada) y una checklist de validación antes de publicar. - Documenta la estructura de directorios recomendada: scripts/, resources/, docs/. ## Cuándo usarla - Necesitas construir una skill personalizada para un flujo de trabajo específico. - Quieres generar una plantilla de skill desde cero. - Necesitas entender la especificación de Claude Skills. ## Qué la activa - "Crea una skill nueva llamada API Builder con frontmatter y quick start" - "Genera la estructura de directorios para una skill con scripts y resources" - "Revisa si mi SKILL.md cumple la checklist de validación" ## Antes de instalar - Requiere Claude Code 2.0+ o Claude.ai con soporte de Skills. ## Archivos - SKILL.md — 21 KB ## SKILL.md Reproducido tal cual desde ruvnet/ruflo bajo MIT. Esta sección es el documento original y está en inglés. # Skill Builder ## What This Skill Does Creates production-ready Claude Code Skills with proper YAML frontmatter, progressive disclosure architecture, and complete file$folder structure. This skill guides you through building skills that Claude can autonomously discover and use across all surfaces (Claude.ai, Claude Code, SDK, API). ## Prerequisites - Claude Code 2.0+ or Claude.ai with Skills support - Basic understanding of Markdown and YAML - Text editor or IDE ## Quick Start ### Creating Your First Skill ```bash # 1. Create skill directory (MUST be at top level, NOT in subdirectories!) mkdir -p ~/.claude$skills$my-first-skill # 2. Create SKILL.md with proper format cat > ~/.claude$skills$my-first-skill/SKILL.md << 'EOF' --- name: "My First Skill" description: "Brief description of what this skill does and when Claude should use it. Maximum 1024 characters." --- # My First Skill ## What This Skill Does [Your instructions here] ## Quick Start [Basic usage] EOF # 3. Verify skill is detected # Restart Claude Code or refresh Claude.ai ``` --- ## Complete Specification ### 📋 YAML Frontmatter (REQUIRED) Every SKILL.md **must** start with YAML frontmatter containing exactly two required fields: ```yaml --- name: "Skill Name" # REQUIRED: Max 64 chars description: "What this skill does # REQUIRED: Max 1024 chars and when Claude should use it." # Include BOTH what & when --- ``` #### Field Requirements **`name`** (REQUIRED): - **Type**: String - **Max Length**: 64 characters - **Format**: Human-friendly display name - **Usage**: Shown in skill lists, UI, and loaded into Claude's system prompt - **Best Practice**: Use Title Case, be concise and descriptive - **Examples**: - ✅ "API Documentation Generator" - ✅ "React Component Builder" - ✅ "Database Schema Designer" - ❌ "skill-1" (not descriptive) - ❌ "This is a very long skill name that exceeds sixty-four characters" (too long) **`description`** (REQUIRED): - **Type**: String - **Max Length**: 1024 characters - **Format**: Plain text or minimal markdown - **Content**: MUST include: 1. **What** the skill does (functionality) 2. **When** Claude should invoke it (trigger conditions) - **Usage**: Loaded into Claude's system prompt for autonomous matching - **Best Practice**: Front-load key trigger words, be specific about use cases - **Examples**: - ✅ "Generate OpenAPI 3.0 documentation from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications." - ✅ "Create React functional components with TypeScript, hooks, and tests. Use when scaffolding new components or converting class components." - ❌ "A comprehensive guide to API documentation" (no "when" clause) - ❌ "Documentation tool" (too vague) #### YAML Formatting Rules ```yaml --- # ✅ CORRECT: Simple string name: "API Builder" description: "Creates REST APIs with Express and TypeScript." # ✅ CORRECT: Multi-line description name: "Full-Stack Generator" description: "Generates full-stack applications with React frontend and Node.js backend. Use when starting new projects or scaffolding applications." # ✅ CORRECT: Special characters quoted name: "JSON:API Builder" description: "Creates JSON:API compliant endpoints: pagination, filtering, relationships." # ❌ WRONG: Missing quotes with special chars name: API:Builder # YAML parse error! # ❌ WRONG: Extra fields (ignored but discouraged) name: "My Skill" description: "My description" version: "1.0.0" # NOT part of spec author: "Me" # NOT part of spec tags: ["dev", "api"] # NOT part of spec --- ``` **Critical**: Only `name` and `description` are used by Claude. Additional fields are ignored. --- ### 📂 Directory Structure #### Minimal Skill (Required) ``` ~/.claude$skills/ # Personal skills location └── my-skill/ # Skill directory (MUST be at top level!) └── SKILL.md # REQUIRED: Main skill file ``` **IMPORTANT**: Skills MUST be directly under `~/.claude$skills/[skill-name]/`. Claude Code does NOT support nested subdirectories or namespaces! #### Full-Featured Skill (Recommended) ``` ~/.claude$skills/ └── my-skill/ # Top-level skill directory ├── SKILL.md # REQUIRED: Main skill file ├── README.md # Optional: Human-readable docs ├── scripts/ # Optional: Executable scripts │ ├── setup.sh │ ├── validate.js │ └── deploy.py ├── resources/ # Optional: Supporting files │ ├── templates/ │ │ ├── api-template.js │ │ └── component.tsx │ ├── examples/ │ │ └── sample-output.json │ └── schemas/ │ └── config-schema.json └── docs/ # Optional: Additional documentation ├── ADVANCED.md ├── TROUBLESHOOTING.md └── API_REFERENCE.md ``` #### Skills Locations **Personal Skills** (available across all projects): ``` ~/.claude$skills/ └── [your-skills]/ ``` - **Path**: `~/.claude$skills/` or `$HOME/.claude$skills/` - **Scope**: Available in all projects for this user - **Version Control**: NOT committed to git (outside repo) - **Use Case**: Personal productivity tools, custom workflows **Project Skills** (team-shared, version controlled): ``` /.claude$skills/ └── [team-skills]/ ``` - **Path**: `.claude$skills/` in project root - **Scope**: Available only in this project - **Version Control**: SHOULD be committed to git - **Use Case**: Team workflows, project-specific tools, shared knowledge --- ### 🎯 Progressive Disclosure Architecture Claude Code uses a **3-level progressive disclosure system** to scale to 100+ skills without context penalty: #### Level 1: Metadata (Name + Description) **Loaded**: At Claude Code startup, always **Size**: ~200 chars per skill **Purpose**: Enable autonomous skill matching **Context**: Loaded into system prompt for ALL skills ```yaml --- name: "API Builder" # 11 chars description: "Creates REST APIs..." # ~50 chars --- # Total: ~61 chars per skill # 100 skills = ~6KB context (minimal!) ``` #### Level 2: SKILL.md Body **Loaded**: When skill is triggered$matched **Size**: ~1-10KB typically **Purpose**: Main instructions and procedures **Context**: Only loaded for ACTIVE skills ```markdown # API Builder ## What This Skill Does [Main instructions - loaded only when skill is active] ## Quick Start [Basic procedures] ## Step-by-Step Guide [Detailed instructions] ``` #### Level 3+: Referenced Files **Loaded**: On-demand as Claude navigates **Size**: Variable (KB to MB) **Purpose**: Deep reference, examples, schemas **Context**: Loaded only when Claude accesses specific files ```markdown # In SKILL.md See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. See [API Reference](docs/API_REFERENCE.md) for complete documentation. Use template: `resources$templates$api-template.js` # Claude will load these files ONLY if needed ``` **Benefit**: Install 100+ skills with ~6KB context. Only active skill content (1-10KB) enters context. --- ### 📝 SKILL.md Content Structure #### Recommended 4-Level Structure ```markdown --- name: "Your Skill Name" description: "What it does and when to use it" --- # Your Skill Name ## Level 1: Overview (Always Read First) Brief 2-3 sentence description of the skill. ## Prerequisites - Requirement 1 - Requirement 2 ## What This Skill Does 1. Primary function 2. Secondary function 3. Key benefit --- ## Level 2: Quick Start (For Fast Onboarding) ### Basic Usage ```bash # Simplest use case command --option value ``` ### Common Scenarios 1. **Scenario 1**: How to... 2. **Scenario 2**: How to... --- ## Level 3: Detailed Instructions (For Deep Work) ### Step-by-Step Guide #### Step 1: Initial Setup ```bash # Commands ``` Expected output: ``` Success message ``` #### Step 2: Configuration - Configuration option 1 - Configuration option 2 #### Step 3: Execution - Run the main command - Verify results ### Advanced Options #### Option 1: Custom Configuration ```bash # Advanced usage ``` #### Option 2: Integration ```bash # Integration steps ``` --- ## Level 4: Reference (Rarely Needed) ### Troubleshooting #### Issue: Common Problem **Symptoms**: What you see **Cause**: Why it happens **Solution**: How to fix ```bash # Fix command ``` #### Issue: Another Problem **Solution**: Steps to resolve ### Complete API Reference See [API_REFERENCE.md](docs/API_REFERENCE.md) ### Examples See [examples/](resources$examples/) ### Related Skills - [Related Skill 1](#) - [Related Skill 2](#) ### Resources - [External Link 1](https:/$example.com) - [Documentation](https:/$docs.example.com) ``` --- ### 🎨 Content Best Practices #### Writing Effective Descriptions **Front-Load Keywords**: ```yaml # ✅ GOOD: Keywords first description: "Generate TypeScript interfaces from JSON schema. Use when converting schemas, creating types, or building API clients." # ❌ BAD: Keywords buried description: "This skill helps developers who need to work with JSON schemas by providing a way to generate TypeScript interfaces." ``` **Include Trigger Conditions**: ```yaml # ✅ GOOD: Clear "when" clause description: "Debug React performance issues using Chrome DevTools. Use when components re-render unnecessarily, investigating slow updates, or optimizing bundle size." # ❌ BAD: No trigger conditions description: "Helps with React performance debugging." ``` **Be Specific**: ```yaml # ✅ GOOD: Specific technologies description: "Create Express.js REST endpoints with Joi validation, Swagger docs, and Jest tests. Use when building new APIs or adding endpoints." # ❌ BAD: Too generic description: "Build API endpoints with proper validation and testing." ``` #### Progressive Disclosure Writing **Keep Level 1 Brief** (Overview): ```markdown ## What This Skill Does Creates production-ready React components with TypeScript, hooks, and tests in 3 steps. ``` **Level 2 for Common Paths** (Quick Start): ```markdown ## Quick Start ```bash # Most common use case (80% of users) generate-component MyComponent ``` ``` **Level 3 for Details** (Step-by-Step): ```markdown ## Step-by-Step Guide ### Creating a Basic Component 1. Run generator 2. Choose template 3. Customize options [Detailed explanations] ``` **Level 4 for Edge Cases** (Reference): ```markdown ## Advanced Configuration For complex scenarios like HOCs, render props, or custom hooks, see [ADVANCED.md](docs/ADVANCED.md). ``` --- ### 🛠️ Adding Scripts and Resources #### Scripts Directory **Purpose**: Executable scripts that Claude can run **Location**: `scripts/` in skill directory **Usage**: Referenced from SKILL.md Example: ```bash # In skill directory scripts/ ├── setup.sh # Initialization script ├── validate.js # Validation logic ├── generate.py # Code generation └── deploy.sh # Deployment script ``` Reference from SKILL.md: ```markdown ## Setup Run the setup script: ```bash .$scripts$setup.sh ``` ## Validation Validate your configuration: ```bash node scripts$validate.js config.json ``` ``` #### Resources Directory **Purpose**: Templates, examples, schemas, static files **Location**: `resources/` in skill directory **Usage**: Referenced or copied by scripts Example: ```bash resources/ ├── templates/ │ ├── component.tsx.template │ ├── test.spec.ts.template │ └── story.stories.tsx.template ├── examples/ │ ├── basic-example/ │ ├── advanced-example/ │ └── integration-example/ └── schemas/ ├── config.schema.json └── output.schema.json ``` Reference from SKILL.md: ```markdown ## Templates Use the component template: ```bash cp resources$templates$component.tsx.template src$components/MyComponent.tsx ``` ## Examples See working examples in `resources$examples/`: - `basic-example/` - Simple component - `advanced-example/` - With hooks and context ``` --- ### 🔗 File References and Navigation Claude can navigate to referenced files automatically. Use these patterns: #### Markdown Links ```markdown See [Advanced Configuration](docs/ADVANCED.md) for complex scenarios. See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) if you encounter errors. ``` #### Relative File Paths ```markdown Use the template located at `resources$templates$api-template.js` See examples in `resources$examples$basic-usage/` ``` #### Inline File Content ```markdown ## Example Configuration See `resources$examples$config.json`: ```json { "option": "value" } ``` ``` **Best Practice**: Keep SKILL.md lean (~2-5KB). Move lengthy content to separate files and reference them. Claude will load only what's needed. --- ### ✅ Validation Checklist Before publishing a skill, verify: **YAML Frontmatter**: - [ ] Starts with `---` - [ ] Contains `name` field (max 64 chars) - [ ] Contains `description` field (max 1024 chars) - [ ] Description includes "what" and "when" - [ ] Ends with `---` - [ ] No YAML syntax errors **File Structure**: - [ ] SKILL.md exists in skill directory - [ ] Directory is DIRECTLY in `~/.claude$skills/[skill-name]/` or `.claude$skills/[skill-name]/` - [ ] Uses clear, descriptive directory name - [ ] **NO nested subdirectories** (Claude Code requires top-level structure) **Content Quality**: - [ ] Level 1 (Overview) is brief and clear - [ ] Level 2 (Quick Start) shows common use case - [ ] Level 3 (Details) provides step-by-step guide - [ ] Level 4 (Reference) links to advanced content - [ ] Examples are concrete and runnable - [ ] Troubleshooting section addresses common issues **Progressive Disclosure**: - [ ] Core instructions in SKILL.md (~2-5KB) - [ ] Advanced content in separate docs/ - [ ] Large resources in resources/ directory - [ ] Clear navigation between levels **Testing**: - [ ] Skill appears in Claude's skill list - [ ] Description triggers on relevant queries - [ ] Instructions are clear and actionable - [ ] Scripts execute successfully (if included) - [ ] Examples work as documented --- ## Skill Builder Templates ### Template 1: Basic Skill (Minimal) ```markdown --- name: "My Basic Skill" description: "One sentence what. One sentence when to use." --- # My Basic Skill ## What This Skill Does [2-3 sentences describing functionality] ## Quick Start ```bash # Single command to get started ``` ## Step-by-Step Guide ### Step 1: Setup [Instructions] ### Step 2: Usage [Instructions] ### Step 3: Verify [Instructions] ## Troubleshooting - **Issue**: Problem description - **Solution**: Fix description ``` ### Template 2: Intermediate Skill (With Scripts) ```markdown --- name: "My Intermediate Skill" description: "Detailed what with key features. When to use with specific triggers: scaffolding, generating, building." --- # My Intermediate Skill ## Prerequisites - Requirement 1 - Requirement 2 ## What This Skill Does 1. Primary function 2. Secondary function 3. Integration capability ## Quick Start ```bash .$scripts$setup.sh .$scripts$generate.sh my-project ``` ## Configuration Edit `config.json`: ```json { "option1": "value1", "option2": "value2" } ``` ## Step-by-Step Guide ### Basic Usage [Steps for 80% use case] ### Advanced Usage [Steps for complex scenarios] ## Available Scripts - `scripts$setup.sh` - Initial setup - `scripts$generate.sh` - Code generation - `scripts$validate.sh` - Validation ## Resources - Templates: `resources$templates/` - Examples: `resources$examples/` ## Troubleshooting [Common issues and solutions] ``` ### Template 3: Advanced Skill (Full-Featured) ```markdown --- name: "My Advanced Skill" description: "Comprehensive what with all features and integrations. Use when [trigger 1], [trigger 2], or [trigger 3]. Supports [technology stack]." --- # My Advanced Skill ## Overview [Brief 2-3 sentence description] ## Prerequisites - Technology 1 (version X+) - Technology 2 (version Y+) - API keys or credentials ## What This Skill Does 1. **Core Feature**: Description 2. **Integration**: Description 3. **Automation**: Description --- ## Quick Start (60 seconds) ### Installation ```bash .$scripts$install.sh ``` ### First Use ```bash .$scripts$quickstart.sh ``` Expected output: ``` ✓ Setup complete ✓ Configuration validated → Ready to use ``` --- ## Configuration ### Basic Configuration Edit `config.json`: ```json { "mode": "production", "features": ["feature1", "feature2"] } ``` ### Advanced Configuration See [Configuration Guide](docs/CONFIGURATION.md) --- ## Step-by-Step Guide ### 1. Initial Setup [Detailed steps] ### 2. Core Workflow [Main procedures] ### 3. Integration [Integration steps] --- ## Advanced Features ### Feature 1: Custom Templates ```bash .$scripts$generate.sh --template custom ``` ### Feature 2: Batch Processing ```bash .$scripts$batch.sh --input data.json ``` ### Feature 3: CI/CD Integration See [CI/CD Guide](docs/CICD.md) --- ## Scripts Reference | Script | Purpose | Usage | |--------|---------|-------| | `install.sh` | Install dependencies | `.$scripts$install.sh` | | `generate.sh` | Generate code | `.$scripts$generate.sh [name]` | | `validate.sh` | Validate output | `.$scripts$validate.sh` | | `deploy.sh` | Deploy to environment | `.$scripts$deploy.sh [env]` | --- ## Resources ### Templates - `resources$templates$basic.template` - Basic template - `resources$templates$advanced.template` - Advanced template ### Examples - `resources$examples$basic/` - Simple example - `resources$examples$advanced/` - Complex example - `resources$examples$integration/` - Integration example ### Schemas - `resources$schemas$config.schema.json` - Configuration schema - `resources$schemas$output.schema.json` - Output validation --- ## Troubleshooting ### Issue: Installation Failed **Symptoms**: Error during `install.sh` **Cause**: Missing dependencies **Solution**: ```bash # Install prerequisites npm install -g required-package .$scripts$install.sh --force ``` ### Issue: Validation Errors **Symptoms**: Validation script fails **Solution**: See [Troubleshooting Guide](docs/TROUBLESHOOTING.md) --- ## API Reference Complete API documentation: [API_REFERENCE.md](docs/API_REFERENCE.md) ## Related Skills - [Related Skill 1](..$related-skill-1/) - [Related Skill 2](..$related-skill-2/) ## Resources - [Official Documentation](https:/$example.com$docs) - [GitHub Repository](https:/$github.com$example$repo) - [Community Forum](https:/$forum.example.com) --- **Created**: 2025-10-19 **Category**: Advanced **Difficulty**: Intermediate **Estimated Time**: 15-30 minutes ``` --- ## Examples from the Wild ### Example 1: Simple Documentation Skill ```markdown --- name: "README Generator" description: "Generate comprehensive README.md files for GitHub repositories. Use when starting new projects, documenting code, or improving existing READMEs." --- # README Generator ## What This Skill Does Creates well-structured README.md files with badges, installation, usage, and contribution sections. ## Quick Start ```bash # Answer a few questions .$scripts$generate-readme.sh # README.md created with: # - Project title and description # - Installation instructions # - Usage examples # - Contribution guidelines ``` ## Customization Edit sections in `resources$templates$sections/` before generating. ``` ### Example 2: Code Generation Skill ```markdown --- name: "React Component Generator" description: "Generate React functional components with TypeScript, hooks, tests, and Storybook stories. Use when creating new components, scaffolding UI, or following component architecture patterns." --- # React Component Generator ## Prerequisites - Node.js 18+ - React 18+ - TypeScript 5+ ## Quick Start ```bash .$scripts$generate-component.sh MyComponent # Creates: # - src$components/MyComponent/MyComponent.tsx # - src$components/MyComponent/MyComponent.test.tsx # - src$components/MyComponent/MyComponent.stories.tsx # - src$components/MyComponent$index.ts ``` ## Step-by-Step Guide ### 1. Run Generator ```bash .$scripts$generate-component.sh ComponentName ``` ### 2. Choose Template - Basic: Simple functional component - With State: useState hooks - With Context: useContext integration - With API: Data fetching component ### 3. Customize Edit generated files in `src$components/ComponentName/` ## Templates See `resources$templates/` for available component templates. ``` --- ## Learn More ### Official Resources - [Anthropic Agent Skills Documentation](https:/$docs.claude.com$en$docs$agents-and-tools$agent-skills) - [GitHub Skills Repository](https:/$github.com$anthropics$skills) - [Claude Code Documentation](https:/$docs.claude.com$en$docs$claude-code) ### Community - [Skills Marketplace](https:/$github.com$anthropics$skills) - Browse community skills - [Anthropic Discord](https:/$discord.gg$anthropic) - Get help from community ### Advanced Topics - Multi-file skills with complex navigation - Skills that spawn other skills - Integration with MCP tools - Dynamic skill generation --- **Created**: 2025-10-19 **Version**: 1.0.0 **Maintained By**: agentic-flow team **License**: MIT ## Dónde encaja - Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código. - Creador: [ruvnet](https://skillsagentes.com/creators/ruvnet.md) — 275 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Harness Gepa](https://skillsagentes.com/skills/ruvnet/ruflo/harness-gepa.md): Inspecciona y audita genomas GEPA: carga y valida un genoma, renderiza el system prompt que compila, o clasifica los modos de fallo de una transcripción de ejecución. - [Deepseek Reason](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-reason.md): Completion en modo razonamiento contra deepseek-reasoner (R1) de DeepSeek. Devuelve el chain-of-thought por separado de la respuesta final. Lee DEEPSEEK_API_KEY y degrada si falta o la API no responde. - [Deepseek Chat](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-chat.md): Completion de un solo turno contra el modelo deepseek-chat de DeepSeek vía /v1/chat/completions. Lee DEEPSEEK_API_KEY y degrada con status:degraded si falta o la API no responde. Para tareas sin razonamiento. - [Adr Index](https://skillsagentes.com/skills/ruvnet/ruflo/adr-index.md): Construye o reconstruye el índice de ADRs y su grafo de dependencias ejecutando scripts/import.mjs, en vez de cientos de llamadas MCP. - [Agntcy Status](https://skillsagentes.com/skills/ruvnet/ruflo/agntcy-status.md): Muestra el estado de la integración AGNTCY/SLIM/CASA: si los paquetes están instalados, qué transporte está activo y si el enforcement de CASA está habilitado. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)