Práctica De IA on KnightLi Blog

Cómo crear y utilizar habilidades: especificación y principios prácticos de SKILL.md

Sat, 28 Mar 2026 16:30:00 +0800

Este artículo se centra en dos preguntas:

¿Cómo debería escribirse y estructurarse SKILL.md?
¿Cómo creamos habilidades reutilizables, mantenibles y de alta calidad?

1. Especificación de HABILIDAD.md

SKILL.md es el archivo de descripción principal de una habilidad. Suele contener dos partes:

Portada de YAML: define metadatos de habilidades.
Cuerpo de Markdown: define la guía de ejecución y el flujo de trabajo práctico.

1.1 Ejemplo de portada

---
# === Required fields ===
name: skill-name
# Unique skill identifier; kebab-case is recommended

description: >
  Brief but precise description of:
  1) What this skill does
  2) When it should be used
  3) What its core value is
# Note: description is typically the key basis for skill selection

# === Optional fields ===
version: 1.0.0
allowed_tools: [tool1, tool2]
required_context: [context_item1]
license: MIT
author: Your Name <email@example.com>
tags: [database, analysis, sql]
---

1.2 Estructura corporal recomendada

# Skill Title

## Overview
(Skill summary, use cases, technical background)

## Prerequisites
(Runtime environment, dependencies, required permissions)

## Workflow
(Step-by-step guidance: input, process, output)

## Best Practices
(Experience-based tips, caveats, common pitfalls)

## Examples
(Typical cases for faster adoption)

## Troubleshooting
(Common issues and fixes)

2. Principios para escribir habilidades de alta calidad

Con base en la documentación oficial y la práctica comunitaria, se recomiendan los siguientes cuatro principios.

2.1 Mantenga la descripción precisa

La “descripción” es el punto de entrada clave para combinar habilidades. Debería:

Definir claramente el alcance; Evite palabras vagas como “ayuda con el procesamiento de datos”.
Incluya palabras clave desencadenantes para que coincidan con la intención del usuario.
Explicar el valor único y los límites de otras habilidades.

Ejemplo débil:

`1`	`description: Handle database queries`

Ejemplo más fuerte:

description: >
  Convert Chinese business questions into SQL queries and analyze the MySQL employees sample database.
  Suitable for employee info lookup, salary statistics, department analysis, and role-change history.
  Use this skill when users ask about employee, salary, or department data.

2.2 Diseño modular y responsabilidad única

Una habilidad debe centrarse en un dominio de tarea claramente definido. Si una sola habilidad intenta abarcar demasiado, a menudo conduce a:

Descripciones más amplias y menor precisión de coincidencia.
Instrucciones más largas y carga de contexto más pesada.
Mayores costes de mantenimiento e iteración.

En lugar de una habilidad de “análisis general”, divídala en habilidades especializadas, por ejemplo:

análisis-de-empleados-mysql
análisis-de-datos-de-ventas
análisis-de-comportamiento-de-usuario

2.3 El determinismo primero

Para tareas complejas que requieren precisión, prefiera la ejecución con script a la generación pura de LLM.

Por ejemplo, en escenarios de exportación de datos, en lugar de generar contenido binario de Excel directamente con un LLM, utilice un script dedicado. SKILL.md solo debe definir cuándo y cómo invocarlo.

2.4 Divulgación progresiva

Capa de información por importancia y frecuencia para reducir el uso de contexto innecesario:

Cuerpo SKILL.md: flujo de trabajo principal y patrones comunes
Documentos complementarios (por ejemplo, advanced.md): uso avanzado y casos extremos
Archivos de datos: datos de referencia de gran tamaño a los que se accede bajo demanda mediante scripts

Resumen

El objetivo de las habilidades de alta calidad no es escribir más, sino establecer límites más claros, mejores desencadenantes, ejecución estable y mantenimiento sostenible.

Comience con un SKILL.md estandarizado, luego combine la responsabilidad única con la divulgación progresiva para construir un sistema de habilidades más eficiente.

Cómo los no programadores pueden dirigir la IA para que haga el trabajo: extraer diagramas y fórmulas matemáticas de una imagen (ejemplo práctico)

Thu, 26 Mar 2026 00:00:00 +0000

Requisitos previos

Instale VS Code y la extensión Codex. Puede consultar [este artículo] (../01/index.md).
El uso de estas herramientas no requiere experiencia en programación. En este flujo de trabajo, VS Code sirve principalmente para organizar archivos; usted describe su objetivo y la IA escribe y ejecuta el código por usted.
Esta publicación registra el proceso completo para generar ideas y ayudar a más personas a descubrir formas prácticas de utilizar la IA.

Objetivo

Prepare una imagen que contenga fórmulas matemáticas y diagramas ilustrativos:

Queremos lograr tres cosas:

Divida los diagramas en imágenes limpias y separadas.
Reconozca fórmulas y conviértalas a LaTeX para editarlas más fácilmente.
Vincula cada diagrama a su fórmula correspondiente.

Proceso

Primero, reconozca la imagen, genere un documento Markdown y convierta fórmulas a LaTeX.

Resultado de la conversión:

# 1.png Recognition Result

## Geometry Formulas (LaTeX)

1. Triangle area (side lengths and circumradius):

$$
S = \frac{abc}{4R}
$$

2. Triangle area (inradius and semiperimeter):

$$
S = pr
$$

3. Frustum volume:

$$
V = \frac{\pi\left(r^2 + Rr + R^2\right)h}{3}
$$

4. Frustum lateral surface area:

$$
S = \pi a(R + r)
$$

5. Cylinder volume:

$$
V = \pi r^2 h
$$

6. Cylinder lateral surface area:

$$
S = 2\pi rh
$$

7. Sphere volume:

$$
V = \frac{4}{3}\pi R^3
$$

8. Sphere surface area:

$$
S = 4\pi R^2
$$

9. Law of sines:

$$
\frac{a}{\sin A}=\frac{b}{\sin B}=\frac{c}{\sin C}=2R
$$

10. Law of cosines:

$$
a^2=b^2+c^2-2bc\cos A
$$

$$
b^2=a^2+c^2-2ac\cos B
$$

$$
c^2=a^2+b^2-2ab\cos C
$$

Se reconocieron todas las fórmulas y la IA incluso agregó nombres de fórmulas automáticamente, lo cual es genial. Sin embargo, los cultivos del diagrama pequeño aún no se generaron.

Intente pedirle a AI que recorte la imagen.

# 1.png Recognition Result (side-by-side layout with refined cropping)

<table>
  <tr>
    <td>![](crops/01_triangle_circum.png)</td>
    <td>

$$
S = \frac{abc}{4R}
$$

</td>
  </tr>
  <tr>
    <td>![](crops/02_triangle_incircle.png)</td>
    <td>

$$
S = pr
$$

</td>
  </tr>
  <tr>
    <td>![](crops/03_frustum.png)</td>
    <td>

$$
V = \frac{\pi\left(r^2 + Rr + R^2\right)h}{3}
$$

$$
S = \pi a(R + r)
$$

</td>
  </tr>
  <tr>
    <td>![](crops/04_cylinder.png)</td>
    <td>

$$
V = \pi r^2 h
$$

$$
S = 2\pi rh
$$

</td>
  </tr>
  <tr>
    <td>![](crops/05_sphere.png)</td>
    <td>

$$
V = \frac{4}{3}\pi R^3
$$

$$
S = 4\pi R^2
$$

</td>
  </tr>
  <tr>
    <td>![](crops/06_laws.png)</td>
    <td>

$$
\frac{a}{\sin A}=\frac{b}{\sin B}=\frac{c}{\sin C}=2R
$$

$$
a^2=b^2+c^2-2bc\cos A
$$

$$
b^2=a^2+c^2-2ac\cos B
$$

$$
c^2=a^2+b^2-2ab\cos C
$$

</td>
  </tr>
</table>

Resultado: Los diagramas fueron recortados y colocados en posiciones coincidentes, pero los cultivos aún incluyen ruido de áreas cercanas.

Corrija el recorte excesivo: mantenga primero el área objetivo completa y luego elimine manualmente las partes adicionales
El resultado aún es inconsistente en este paso. Aún no está claro si el problema proviene de las indicaciones o de la variabilidad del modelo en la localización visual.

Resumen

Usar Codex es diferente a chatear directamente en chatgpt.com.
En chatgpt.com, a menudo parece que la IA guía su trabajo; en Codex, se siente más como si la IA estuviera ejecutando sus instrucciones.
Después de describir sus requisitos, la IA puede generar código, ejecutarlo y completar la tarea. La sensación es que estás dirigiendo a la IA para que haga el trabajo.
Este proceso no requiere grandes habilidades de programación y los no programadores aún pueden obtener resultados reales paso a paso.