Ai-Practice on KnightLi Blog

How to Create and Use Skills: SKILL.md Specification and Practical Principles

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

This article focuses on two questions:

How should SKILL.md be written and structured?
How do we create high-quality, maintainable, reusable Skills?

1. SKILL.md Specification

SKILL.md is the core description file of a skill. It usually contains two parts:

YAML front matter: defines skill metadata.
Markdown body: defines execution guidance and practical workflow.

1.1 Front Matter Example

---
# === 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 Recommended Body Structure

# 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. Principles for Writing High-Quality Skills

Based on official documentation and community practice, the following four principles are recommended.

2.1 Keep Description Precise

description is the key entry point for skill matching. It should:

Clearly define scope; avoid vague wording like “helps with data processing.”
Include trigger keywords to match user intent.
Explain unique value and boundaries from other skills.

Weak example:

`1`	`description: Handle database queries`

Stronger example:

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 Modular Design and Single Responsibility

A skill should focus on one clearly defined task domain. If a single skill tries to cover too much, it often leads to:

Broader descriptions and lower matching precision.
Longer instructions and heavier context load.
Higher maintenance and iteration costs.

Instead of one “general analysis” skill, split into specialized skills, for example:

mysql-employees-analysis
sales-data-analysis
user-behavior-analysis

2.3 Determinism First

For complex tasks requiring precision, prefer scripted execution over pure LLM generation.

For example, in data export scenarios, instead of generating Excel binary content directly with an LLM, use a dedicated script. SKILL.md should only define when and how to invoke it.

2.4 Progressive Disclosure

Layer information by importance and frequency to reduce unnecessary context usage:

SKILL.md body: core workflow and common patterns
Supplementary docs (for example, advanced.md): advanced usage and edge cases
Data files: large reference data accessed on demand via scripts

Summary

The goal of high-quality Skills is not writing more, but writing clearer boundaries, better triggers, stable execution, and sustainable maintenance.

Start with a standardized SKILL.md, then combine single responsibility with progressive disclosure to build a more efficient skill system.

How Non-Programmers Can Direct AI to Do the Work: Extracting Diagrams and Math Formulas from an Image (Hands-On Example)

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

Prerequisites

Install VS Code and the Codex extension. You can refer to this article.
Using these tools does not require programming experience. In this workflow, VS Code is mainly for organizing files; you describe your goal, and AI writes and runs the code for you.
This post records the full process to spark ideas and help more people discover practical ways to use AI.

Goal

Prepare an image that contains both math formulas and illustrative diagrams:

We want to achieve three things:

Split diagrams into clean, separate images.
Recognize formulas and convert them to LaTeX for easier editing.
Link each diagram to its corresponding formula.

Process

First, recognize the image, generate a Markdown document, and convert formulas to LaTeX

Conversion result:

# 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
$$

All formulas were recognized, and AI even added formula names automatically, which is great. However, the small diagram crops were not generated yet.

Try asking AI to crop the image

# 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>

Result: The diagrams were cropped and placed in matching positions, but the crops still include noise from nearby areas.

Fix over-cropping: keep the full target area first, then manually remove extra parts
The output is still inconsistent at this step. It is not yet clear whether the issue comes from prompting or model variability in visual localization.

Summary

Using Codex feels different from chatting directly on chatgpt.com.
On chatgpt.com, it often feels like AI is guiding your work; in Codex, it feels more like AI is executing your instructions.
After you describe your requirement, AI can generate code, run it, and complete the task. The feeling is that you are directing AI to do the work.
This process does not require strong programming skills, and non-programmers can still get real results step by step.