Grundstruktur von Skills

Der Kern von Skills besteht darin, der KI operative Richtlinien bereitzustellen, die standardisierte Ausführungsprozesse definieren. Einmal geschrieben, können diese Regeln wiederholt aufgerufen und direkt wiederverwendet werden, genau wie Programmfunktionen.

Skills werden als Markdown-Text gespeichert und führen selbst keine Funktionen direkt aus.

Skills bieten bedarfsgesteuertes Laden und progressive Aufrufung, sammeln effizient Arbeitserfahrung und ermöglichen schnelle Wiederverwendung und präzise Weitergabe von Fähigkeiten.

---

Die Kernstruktur eines Skills

Der Kern von Skills ist:Ein Ordner + eine SKILL.md-Datei。

Die SKILL.md-Datei enthält:

• Metadaten (mindestens einen Namen und eine Beschreibung)
• Anweisungen, die der KI sagen, wie eine bestimmte Aufgabe zu erledigen ist

Ein Skill ist im Wesentlichen eine Markdown-Datei (der Dateiname ist fest als SKILL.md vorgegeben).

my-skill/
└── SKILL.md   （唯一必需）

SKILL.md-Basisvorlage:

---
name: your-skill-name
description: 一句话描述该 Skill 的功能和使用场景
---

# Skill 名称

## 使用指引
[给 AI 的分步骤行为指引]

## 示例
[该 Skill 的具体使用示例]

Die gesamte SKILL.md ist in zwei Teile unterteilt: Der mit------ umschlossene Teil ist das YAML-Frontmatter (Header-Konfiguration), und der darunter liegende Teil ist der Markdown-Body (Ausführungsanweisungen).

Feld	Erforderlich	Beschreibung	Beispiel
name	Ja	Der eindeutige Bezeichner des Skills, benannt in kebab-case. Er wird von /-Befehlen referenziert und ist das Schlüsselfeld, anhand dessen das System den Skill identifiziert.	web-design-guidelines
description	Ja	Eine Beschreibung der Funktionalität und der Auslöseszenarien in einem Satz. Je spezifischer der Inhalt, desto präziser die Auslösung.	UI/UX design review for web pages

Als Nächstes schlüsseln wir jeden Teil auf:

Frontmatter: Zwei erforderliche Felder

Frontmatter ist der YAML-Konfigurationsblock, der oben in SKILL.md mit --- umschlossen ist und als Identitätsinformation des gesamten Skills dient.

Die offizielle Spezifikation erfordert nur zwei Felder:

Feld 1: name (Name des Skills)

Das Feld name darf bis zu 64 Zeichen lang sein und darf nur Kleinbuchstaben, Zahlen und Bindestriche enthalten.

name: processing-pdfs        # 好：动名词形式，清晰描述功能
name: analyzing-spreadsheets # 好：一眼知道用途
name: my-brand-guidelines    # 好：组织专属知识

name: helper      # 差：太模糊
name: MySkill     # 差：包含大写字母（不合规）
name: data files  # 差：包含空格（不合规）

Für die Benennung wird die Gerundiumform (Verb + -ing) empfohlen, wie z. B. processing-pdfs, analyzing-spreadsheets, um die Aktivität oder Fähigkeit, die der Skill bereitstellt, klar zu beschreiben.

Empfohlen	Nicht empfohlen	Grund
code-reviewer	CodeReviewer	Konsistente Kleinschreibung und Bindestriche verwenden, um plattformübergreifende Kompatibilitätsprobleme zu vermeiden
sql-optimizer	sql_optimizer	kebab-case ist das konventionelle Format und sollte mit dem Verzeichnisnamen konsistent gehalten werden
deploy-check	deploy-check-tool-v2	Der Name sollte kurz sein; Versionsinformationen gehören in die interne Beschreibung der Datei

Feld 2: description (Beschreibung der Auslösebedingung)

Dies ist das wichtigste Feld. Beim Start lädt das System nur den Namen und die Beschreibung aller Skills in den System-Prompt vor.

Nur wenn die KI feststellt, dass die Beschreibung für die aktuelle Aufgabe relevant ist, liest sie den vollständigen Inhalt von SKILL.md.

Die Beschreibung sollte zwei Teile enthalten:Was dieser Skill tut und wann Claude ihn verwenden sollte.

description: |
  Use when the user needs to create, read, edit, or generate Word
  documents (.docx). Triggers include: 'Word doc', 'word document',
  '.docx', 'report', 'letter', 'memo', or any request to produce
  a formatted document for sharing or printing.

Markdown-Body: Interne Struktur der Ausführungsanweisungen

Empfohlen	Nicht empfohlen	Grund
"Python-Code auf SQL-Injection-Risiken scannen und Korrekturvorschläge bereitstellen"	"Ein Sicherheitstool"	Die Beschreibung ist zu vage, um präzise ausgelöst zu werden
"Markdown in HTML-E-Mails umwandeln, die den Markenrichtlinien entsprechen"	"Dateiformate konvertieren"	Es fehlen spezifische Szenarien und es kann bei anderen Aufgaben fälschlicherweise ausgelöst werden

Nach dem Frontmatter folgt der Markdown-Body, der der KI genau vorgibt, wie sie vorgehen soll.

Es enthält mindestens zwei Abschnitte:

SKILL.md-Beispiele

SKILL.md-Basisvorlage:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
---

# PDF 处理

## 使用场景
当需要对 PDF 文件进行操作时使用，例如：

- 提取 PDF 文本或表格数据
- 填写 PDF 表单
- 合并多个 PDF 文件

## 提取文本
- 使用 `pdfplumber` 提取文本型 PDF 内容  
- 扫描版 PDF 需配合 OCR 工具  

## 填写表单
- 读取 PDF 表单字段  
- 按输入数据填充并生成新文件  

Minimal erforderliches Beispiel:

---
name: skill-name
description: 说明该 Skill 的功能以及适用场景
---

Beispiel mit optionalen Feldern:

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Feldbeschreibungen:

Feld	Erforderlich	Beschreibung
name	Ja	Name des Skills, bis zu 64 Zeichen; darf nur Kleinbuchstaben, Zahlen und Bindestriche enthalten-, und darf nicht-mit einem Bindestrich beginnen oder enden
description	Ja	Beschreibung der Funktionalität und der Nutzungsszenarien, bis zu 1024 Zeichen, darf nicht leer sein
license	nein	Lizenzname oder ein Verweis auf die mit dem Skill gebündelte Lizenzdatei
Kompatibilität	nein	Beschreibung der Umgebung und Abhängigkeiten (Produkte, Systempakete, Netzwerkberechtigungen usw.), bis zu 500 Zeichen
metadata	nein	Benutzerdefinierte Schlüssel-Wert-Paare zur Erweiterung von Metadaten (wie z. B. Autor, Version)
allowed-tools	nein	Liste der zulässigen Tools (durch Leerzeichen getrennt, experimentelles Feature)

---

Verzeichnisstruktur der Skill-Dateien

Ein Skill ist ein Ordner, der mindestens eine SKILL.md-Datei enthält und bei Bedarf auch andere Verzeichnisse und Dateien enthalten kann.

Um eine Überladung des Kontexts zu vermeiden:

• Kernregeln →SKILL.md
• Detaillierte Materialien → separate Dateien
• Praktische Logik → Skriptausführung (nicht geladen)

Empfohlene Struktur:

my-skill/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
      └── helper.py
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源
└── ...               # 其他文件或目录

Die Funktion jedes Verzeichnisses ist wie folgt:

• SKILL.md: Erforderliche Datei, die die Metadaten und Ausführungsanweisungen des Skills enthält
• scripts/: Optionales Verzeichnis, das ausführbaren Code enthält, den der Agent ausführen kann
• references/: Optionales Verzeichnis, das detaillierte Referenzmaterialien enthält
• assets/: Optionales Verzeichnis, das statische Assets wie Vorlagen, Bilder usw. enthält

Andere Erweiterungen