SKILL.md-Datei

SKILL.md ist die Kerndatei von Agent Skills.

Dieser Abschnitt befasst sich eingehend mit der vollständigen Struktur von SKILL.md und allen verfügbaren Feldern.


Grundstruktur

Eine SKILL.md-Datei enthält zwei Hauptteile:

  1. YAML-Frontmatter (Metadatenbereich)
  2. Markdown-Inhalt (Anweisungsbereich)

Vollständiges Beispiel

---
name
: my-skill
description
: Skill-Beschreibung, die angibt, wann dieser Skill verwendet werden soll
license
: Apache-2.0
compatibility
: Erfordert Python3.10+
metadata
:
  author
: your-name
  version
: "1.0"
---

# Skill-Name

Hier sind die detaillierten Anweisungen für den Skill...

## Schritt 1

Spezifische Arbeitsschritte...

## Schritt 2

Weitere Bedienschritte...

Metadatenfelder erklärt

Die folgenden sind alle von SKILL.md unterstützten Metadatenfelder:

Feld Erforderlich Einschränkungen
name Ja Bis zu 64 Zeichen, nur Kleinbuchstaben, Ziffern und Bindestriche erlaubt; darf nicht mit einem Bindestrich beginnen oder enden
description Ja Bis zu 1024 Zeichen, beschreibt die Funktion und die Anwendungsszenarien des Skills
license nein Lizenzname oder ein Verweis auf eine mitgelieferte Lizenzdatei
Kompatibilität nein Bis zu 500 Zeichen, gibt Umgebungsanforderungen an (Zielprodukt, Systempakete, Netzwerkzugriff usw.)
metadata nein Beliebige Schlüssel-Wert-Paare zum Speichern zusätzlicher Metadaten
allowed-tools nein Durch Leerzeichen getrennte Liste von vorab genehmigten Tools (experimentelles Feature)

Das Feld name erklärt

Das Feld name ist der Bezeichner des Skills und muss folgenden Regeln entsprechen:

  • Länge: 1-64 Zeichen
  • Zeichenbeschränkung: Es dürfen nur Unicode-Kleinbuchstaben (a-z) und Bindestriche (-) verwendet werden
  • Start/Ende: Darf nicht mit einem Bindestrich beginnen oder enden
  • Aufeinanderfolgende Zeichen: Darf keine aufeinanderfolgenden Bindestriche (--) enthalten
  • Übereinstimmungsanforderung: Muss mit dem Namen des übergeordneten Verzeichnisses übereinstimmen

Gültige Beispiele:

name: pdf-processing
name: data-analysis
name: code-review

Ungültige Beispiele:

name: PDF-Processing   # 错误:不能使用大写字母
name: -pdf           # 错误:不能以连字符开头
name: pdf--processing  # 错误:不能包含连续连字符

Erläuterung des Feldes „description“

Das Feld „description“ ist eines der wichtigsten Felder; es teilt dem Agenten mit, wann er diesen Skill aktivieren sollte.

Eine gute Beschreibung sollte:

  • Beschreiben, was der Skill tut (was er tut)
  • Nutzungsszenarien erklären (wann er verwendet wird)
  • Schlüsselwörter einbeziehen, damit der Agent relevante Aufgaben erkennen kann

Beispiel für eine gute Beschreibung:

description: 从 PDF 文件中提取文本和表格,填写 PDF 表单,合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

Beispiel für eine schlechte Beschreibung:

description: 帮助处理 PDF 文件。  # 太笼统,代理无法判断何时使用

Tipp: Das Feld description wird zu Beginn der Konversation geladen. Stelle sicher, dass es genügend Schlüsselwörter enthält, damit der Agent korrekt erkennen kann, wann der Skill aktiviert werden soll.


Erklärung zum Feld license

Das Feld license wird verwendet, um die Lizenz des Skills anzugeben. Dies ist ein optionales Feld.

license: Apache-2.0
# 或者引用 bundled 的许可证文件
license: Proprietary. LICENSE.txt has complete terms

Erklärung zum Feld compatibility

Das Feld compatibility wird verwendet, um die Umgebungsanforderungen des Skills anzugeben. Es muss nur hinzugefügt werden, wenn der Skill spezielle Umgebungsanforderungen hat.

# 指定目标产品
compatibility: Designed for Claude Code

# 指定系统依赖
compatibility: Requires git, docker, jq, and access to the internet

# 指定编程语言版本
compatibility: Requires Python 3.14+ and uv

Hinweis: Die meisten Skills benötigen das Feld compatibility nicht. Füge es nur hinzu, wenn der Skill wirklich spezifische Umgebungsanforderungen hat.


Erklärung zum Feld metadata

Das Feld metadata kann beliebige Schlüssel-Wert-Paar-Informationen speichern. Clients können es verwenden, um zusätzliche Eigenschaften zu speichern, die nicht in der Spezifikation definiert sind.

metadata:
  author: example-org
  version: "1.0"
  tags:
    - pdf
    - document
    - extraction

Tipp: Es wird empfohlen, relativ eindeutige Schlüsselnamen zu verwenden, um Konflikte mit anderen Skills zu vermeiden.


Erklärung zum Feld allowed-tools

allowed-tools ist ein experimentelles Feld, das verwendet wird, um die vorab genehmigten Tools anzugeben, die von einem Skill verwendet werden können.

allowed-tools: Bash(git:*) Bash(jq:*) Read

Hinweis: Dies ist ein experimentelles Feature; verschiedene Agent-Implementierungen können unterschiedliche Unterstützung bieten.


Erläuterung des Abschnitts „Anweisungen“

Der Markdown-Inhalt nach dem Metadatenbereich ist der Anweisungsteil des Skills. Es gibt hier keine Formatbeschränkungen; Sie können alles nach Bedarf schreiben.

Es wird empfohlen, Folgendes aufzunehmen:

  • Schritt-für-Schritt-Anleitungen
  • Beispiele für Ein- und Ausgaben
  • Umgang mit häufigen Randfällen
# 技能名称

## 功能说明

简要描述这个技能做什么。

## 操作步骤

1. 第一步:执行某个操作
2. 第二步:执行另一个操作
3. 第三步:完成最终操作

## 示例

### 输入示例
描述输入是什么...

### 输出示例
描述输出是什么...

## 注意事项

- 注意点 1
- 注意点 2

Hinweis: Sobald ein Skill aktiviert ist, wird die gesamte SKILL.md-Datei in den Kontext geladen. Es wird empfohlen, die Hauptanweisungen auf höchstens 500 Zeilen und unter 5000 Token zu halten. Verschieben Sie detailliertes Referenzmaterial in separate Dateien.

Andere Erweiterungen