skill-developer

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: skill-developer
description: Create and manage Claude Code skills following Anthropic best practices and the agentskills.io specification. Use when creating new skills, understanding trigger patterns, debugging skill activation, or implementing progressive disclosure. Covers SKILL.md structure, YAML frontmatter schema, trigger types, enforcement levels, hook mechanisms, and progressive disclosure.
---

# Skill Developer Guide

## Purpose

Comprehensive guide for creating and managing skills in Claude Code, following the **[Agent Skills Specification](https://agentskills.io/specification)** and Anthropic's best practices including the 500-line rule and progressive disclosure pattern.

## Agent Skills Specification (agentskills.io)

Skills in this project follow the open **[Agent Skills Specification](https://agentskills.io/specification)**. Key requirements:

### Directory Structure

```
skills/{skill-name}/
├── SKILL.md           # Required - main skill file
├── references/        # Optional - detailed documentation
├── scripts/           # Optional - executable code (Python, Bash, JS)
└── assets/            # Optional - templates, images, data files
```

### SKILL.md Frontmatter Schema

**Required Fields:**
| Field | Requirements |
|-------|-------------|
| `name` | 1-64 chars, lowercase alphanumeric + hyphens, must match directory name |
| `description` | 1-1024 chars, include keywords for agent activation |

**Optional Fields:**
| Field | Purpose |
|-------|---------|
| `license` | License for sharing skills publicly |
| `compatibility` | Environment requirements (packages, network access) |
| `metadata` | Key-value pairs for custom properties |
| `allowed-tools` | Pre-approved tools list (experimental) |

### Progressive Disclosure Model

1. **Metadata** (~100 tokens) - loads at startup
2. **Full instructions** (<5000 tokens recommended) - loads on activation
3. **Supporting files** - loads as needed

### Validation

Use `skills-ref` tool or validate manually:
- File must be named `SKILL.md` (uppercase)
- Name in frontmatter must match parent directory
- Description should include trigger keywords

## When to Use This Skill

Automatically activates when you mention:
- Creating or adding skills
- Modifying skill triggers or rules
- Understanding how skill activation works
- Debugging skill activation issues
- Claude Code best practices
- Progressive disclosure
- YAML frontmatter
- 500-line rule

---

## System Overview

### Skill Activation Approaches

There are several approaches to skill activation, from simple to advanced:

**1. Description-Based Activation (Default)**
- Claude reads skill descriptions from frontmatter at session start
- Activates skills when user prompts match description keywords
- No additional configuration needed
- Works out of the box with the agentskills.io spec

**2. Example Implementation: Hook-Based Activation**

For more sophisticated activation, you can build a hook system. This is an advanced pattern:

**UserPromptSubmit Hook** (Proactive Suggestions)
- Trigger: BEFORE Claude sees user's prompt
- Purpose: Suggest relevant skills based on keywords + intent patterns
- Method: Injects formatted reminder as context (stdout to Claude's input)

**Stop Hook** (Gentle Reminders)
- Trigger: AFTER Claude finishes responding
- Purpose: Gentle reminder to self-assess patterns in code written
- Method: Analyzes edited files for patterns, displays reminder if needed

**Configuration for Hook Systems:**

A rules file (e.g., `skill-rules.json`) can define:
- All skills and their trigger conditions
- Enforcement levels (block, suggest, warn)
- File path patterns (glob)
- Content detection patterns (regex)
- Skip conditions (session tracking, file markers, env vars)

---

## Skill Types

### 1. Guardrail Skills

**Purpose:** Enforce critical best practices that prevent errors

**Characteristics:**
- Type: `"guardrail"`
- Enforcement: `"block"`
- Priority: `"critical"` or `"high"`
- Block file edits