DataShrimp/skills

Proveniencia de la Fuente

• Repositorio Oficial: anthropics/skills — mcp-builder/SKILL.md
• Referencias Adicionales de Ingeniería de Habilidades Incluidas:
  • Claude Code Skills — Inyección Dinámica de Contexto (!comando``)
  • OpenAI ChatGPT & Codex Skills (agents/openai.yaml)
  • Agent Skills Specification — Script Harness (agentskills.io)

---

Parte 1: mcp-builder/SKILL.md Oficial de Anthropic (Ejemplo de Divulgación Progresiva de 3 Niveles)

Vista General

Cree servidores MCP (Model Context Protocol) que permitan a los LLMs interactuar con servicios externos a través de herramientas bien diseñadas. La calidad de un servidor MCP se mide por qué tan bien permite a los LLMs realizar tareas del mundo real.

---

Proceso

🚀 Flujo de Trabajo de Alto Nivel

Crear un servidor MCP de alta calidad implica cuatro fases principales:

Fase 1: Investigación y Planificación Profunda

1.1 Comprender el Diseño Moderno de MCP

Cobertura de API vs. Herramientas de Flujo de Trabajo: Equilibre la cobertura completa de endpoints de API con herramientas de flujo de trabajo especializadas. Las herramientas de flujo de trabajo pueden ser más convenientes para tareas específicas, mientras que la cobertura completa brinda a los agentes flexibilidad para componer operaciones. El rendimiento varía según el cliente: algunos clientes se benefician de la ejecución de código que combina herramientas básicas, mientras que otros funcionan mejor con flujos de trabajo de nivel superior. Cuando no esté seguro, priorice la cobertura completa de API.

Nomenclatura y Descubribilidad de Herramientas: Los nombres de herramientas claros y descriptivos ayudan a los agentes a encontrar las herramientas adecuadas rápidamente. Use prefijos consistentes (por ejemplo, github_create_issue, github_list_repos) y nombres orientados a la acción.

Gestión de Contexto: Los agentes se benefician de descripciones de herramientas concisas y la capacidad de filtrar/paginar resultados. Diseñe herramientas que devuelvan datos enfocados y relevantes. Algunos clientes admiten la ejecución de código, lo que puede ayudar a los agentes a filtrar y procesar datos de manera eficiente.

Mensajes de Error Accionables: Los mensajes de error deben guiar a los agentes hacia soluciones con sugerencias específicas y próximos pasos.

1.2 Estudiar la Documentación del Protocolo MCP

Navegue por la especificación MCP: Comience con el mapa del sitio para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml Luego obtenga páginas específicas con el sufijo .md para formato markdown (por ejemplo, https://modelcontextprotocol.io/specification/draft.md).

Páginas clave a revisar:

• Descripción general y arquitectura de la especificación
• Mecanismos de transporte (HTTP transmisible, stdio)
• Definiciones de herramientas, recursos y prompts

1.3 Estudiar la Documentación del Framework

Stack recomendado:

• Lenguaje: TypeScript (soporte SDK de alta calidad y buena compatibilidad en muchos entornos de ejecución, p. ej., MCPB. Además, los modelos de IA son buenos generando código TypeScript, beneficiándose de su amplio uso, tipado estático y buenas herramientas de linting)
• Transporte: HTTP transmisible para servidores remotos, usando JSON sin estado (más simple de escalar y mantener, en comparación con sesiones con estado y respuestas en streaming). stdio para servidores locales.

Cargue la documentación del framework:

• Mejores Prácticas MCP: 📋 Ver Mejores Prácticas - Guías principales para todos los servidores MCP
• Para TypeScript (recomendado): ⚡ Guía de TypeScript - Patrones y ejemplos de TypeScript
• Para Python: 🐍 Guía de Python - Patrones y ejemplos de Python/FastMCP

1.4 Planifique su Implementación

Entienda la API: Revise la documentación de la API del servicio para identificar endpoints clave, requisitos de autenticación y modelos de datos. Use búsqueda web y fetch web según sea necesario.

Selección de Herramientas: Priorice la cobertura completa de API. Enumere los endpoints a implementar, comenzando con las operaciones más comunes.

---

Fase 2: Implementación

2.1 Configurar la Estructura del Proyecto

Consulte las guías específicas de lenguaje para la configuración del proyecto:

• ⚡ Guía de TypeScript - Estructura del proyecto, package.json, tsconfig.json
• 🐍 Guía de Python - Organización de módulos, dependencias

2.2 Implementar la Infraestructura Central

Cree utilidades compartidas:

• Cliente de API con autenticación
• Ayudantes de manejo de errores
• Formateo de respuestas (JSON y Markdown)
• Soporte de paginación

2.3 Implementar Herramientas

Para cada herramienta:

Esquema de Entrada:

• Use Zod (TypeScript) o Pydantic (Python)
• Incluya restricciones y descripciones claras
• Agregue ejemplos en las descripciones de los campos

Esquema de Salida:

• Defina outputSchema cuando sea posible para datos estructurados
• Use structuredContent en las respuestas de la herramienta (característica del SDK de TypeScript)
• Ayuda a los clientes a entender y procesar las salidas de las herramientas

Descripción de la Herramienta:

• Resumen conciso de la funcionalidad
• Descripciones de parámetros
• Esquema del valor de retorno

Implementación:

• Async/await para operaciones de E/S
• Manejo adecuado de errores con mensajes accionables
• Soporte de paginación donde corresponda
• Devuelva tanto contenido de texto como datos estructurados cuando use SDKs modernos

Anotaciones:

• readOnlyHint: true/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

Fase 3: Revisión y Pruebas

3.1 Calidad del Código

Revise para:

• Sin código duplicado (principio DRY)
• Manejo de errores consistente
• Cobertura total de tipos
• Descripciones de herramientas claras

3.2 Compilación y Pruebas

TypeScript:

• Ejecute npm run build para verificar la compilación
• Pruebe con MCP Inspector: npx @modelcontextprotocol/inspector

Python:

• Verifique la sintaxis: python -m py_compile your_server.py
• Pruebe con MCP Inspector

Consulte las guías específicas de lenguaje para enfoques de prueba detallados y listas de verificación de calidad.

---

Fase 4: Crear Evaluaciones

Después de implementar su servidor MCP, cree evaluaciones integrales para probar su efectividad.

Cargue ✅ Guía de Evaluación para pautas completas de evaluación.

4.1 Entender el Propósito de la Evaluación

Use evaluaciones para probar si los LLMs pueden usar efectivamente su servidor MCP para responder preguntas realistas y complejas.

4.2 Crear 10 Preguntas de Evaluación

Para crear evaluaciones efectivas, siga el proceso descrito en la guía de evaluación:

1. Inspección de Herramientas: Enumere las herramientas disponibles y comprenda sus capacidades
2. Exploración de Contenido: Use operaciones de SÓLO LECTURA para explorar los datos disponibles
3. Generación de Preguntas: Cree 10 preguntas complejas y realistas
4. Verificación de Respuestas: Resuelva cada pregunta usted mismo para verificar las respuestas

4.3 Requisitos de las Evaluaciones

Asegúrese de que cada pregunta sea:

• Independiente: No dependiente de otras preguntas
• Solo lectura: Solo se requieren operaciones no destructivas
• Compleja: Requiere múltiples llamadas a herramientas y exploración profunda
• Realista: Basada en casos de uso reales que importarían a los humanos
• Verificable: Respuesta única y clara que pueda verificarse mediante comparación de cadenas
• Estable: La respuesta no cambiará con el tiempo

4.4 Formato de Salida

Cree un archivo XML con esta estructura:

<evaluation>
  <qa_pair>
    <question>Encuentre discusiones sobre lanzamientos de modelos de IA con nombres en clave de animales. Un modelo necesitaba una designación de seguridad específica que usa el formato ASL-X. ¿Qué número X se estaba determinando para el modelo con nombre de un felino salvaje manchado?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Más qa_pairs... -->
</evaluation>

---

Archivos de Referencia

📚 Biblioteca de Documentación

Cargue estos recursos según sea necesario durante el desarrollo:

Documentación Principal de MCP (Cargar Primero)

• Protocolo MCP: Comience con el mapa del sitio en https://modelcontextprotocol.io/sitemap.xml, luego obtenga páginas específicas con el sufijo .md
• 📋 Mejores Prácticas MCP - Pautas universales de MCP que incluyen:
  • Convenciones de nomenclatura de servidores y herramientas
  • Pautas de formato de respuesta (JSON vs Markdown)
  • Mejores prácticas de paginación
  • Selección de transporte (HTTP transmisible vs stdio)
  • Estándares de seguridad y manejo de errores

Documentación del SDK (Cargar Durante la Fase 1/2)

• SDK de Python: Obtener de https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• SDK de TypeScript: Obtener de https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guías de Implementación Específicas de Lenguaje (Cargar Durante la Fase 2)

• 🐍 Guía de Implementación de Python
• ⚡ Guía de Implementación de TypeScript

Guía de Evaluación (Cargar Durante la Fase 4)

• ✅ Guía de Evaluación

---

Parte 2: Ejemplo de Habilidad de Inyección Dinámica de Contexto de Claude Code (!comando``)

• Fuente: Documentación de Claude Code Skills

---
name: pr-summary
description: Resumir cambios en una pull request. Úselo cuando el usuario pida revisar, resumir o auditar la PR actual o el diff de la rama.
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Contexto de la pull request
- Diff de la PR: !`gh pr diff`
- Comentarios de la PR: !`gh pr view --comments`
- Archivos modificados: !`gh pr diff --name-only`

## Su tarea
Resuma esta pull request con riesgos concretos a nivel de archivo, cambios disruptivos y pasos de verificación...

---

Parte 3: Esquema Sidecar agents/openai.yaml de OpenAI Codex / ChatGPT

• Fuente: Documentación de OpenAI Build Skills

interface:
  display_name: "Meta-Prompt Auto-Evolutivo y Arquitecto de Roles"
  short_description: "Compilar, evaluar y adaptar Prompts, Habilidades y Roles de Agente entre herramientas"
  icon_small: "./assets/icon-small.svg"
  icon_large: "./assets/icon-large.png"
  brand_color: "#2563EB"
  default_prompt: "Diseñar u optimizar una definición de prompt, habilidad o rol de agente con una tarjeta de puntuación de evaluación."

policy:
  allow_implicit_invocation: true

dependencies:
  tools:
    - type: "mcp"
      value: "git"
      description: "Servidor MCP de Git para inspección de repositorios"

---

Parte 4: Ejemplo de Script Autónomo PEP 723 para Agent Skills

• Fuente: Agent Skills — Uso de Scripts (agentskills.io)

# /// script
# dependencies = [
#   "pydantic>=2.0",
# ]
# requires-python = ">=3.10"
# ///
"""Script CLI autónomo no interactivo diseñado para invocación de Agent Skill mediante `uv run`."""

import argparse
import json
import sys


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Validar frontmatter de habilidad o rol y presupuesto de tokens sin mensajes interactivos."
    )
    parser.add_argument("--input", required=True, help="Ruta al archivo Markdown de destino")
    parser.add_argument("--max-chars", type=int, default=12000, help="Techo del presupuesto de caracteres")
    parser.add_argument("--dry-run", action="store_true", help="Previsualizar verificaciones sin escribir")
    args = parser.parse_args()

    try:
        with open(args.input, "r", encoding="utf-8") as f:
            text = f.read()
    except FileNotFoundError:
        sys.stderr.write(
            f"Error: Archivo '{args.input}' no encontrado. Pase una ruta válida mediante --input <ruta>.\n"
        )
        return 1

    char_count = len(text)
    passed = char_count <= args.max_chars
    result = {
        "file": args.input,
        "char_count": char_count,
        "max_chars": args.max_chars,
        "passed": passed,
        "remediation": None if passed else f"Recorte {char_count - args.max_chars} caracteres o mueva detalles a references/.",
    }
    sys.stdout.write(json.dumps(result, ensure_ascii=False, indent=2) + "\n")
    return 0 if passed else 2


if __name__ == "__main__":
    sys.exit(main())