Extension de scripts pour les compétences

En plus d’écrire des instructions dans SKILL.md, vous pouvez également ajouter du code exécutable à une compétence via le répertoire scripts.

Cette section vous apprendra à utiliser des scripts pour étendre les fonctionnalités d’une compétence.

Pourquoi utiliser des scripts

L’utilisation de scripts vous permet de :

  • Encapsuler une logique complexe et éviter d’écrire de grandes quantités de code dans SKILL.md
  • Fournir des implémentations testées et fiables
  • Permettre aux agents de réutiliser les mêmes outils et fonctions
  • Gérer des opérations d’entrée/sortie plus complexes

Astuce : lorsque vous remarquez que l’agent implémente de façon répétée la même logique au fil de multiples exécutions, c’est souvent un bon moment pour créer un script.

Structure du répertoire de scripts

Les scripts doivent être placés dans le sous-répertoire scripts/ du répertoire de la compétence :

Structure du répertoire

my-skill/
├── SKILL.md
└── scripts/
    ├── script1.py
    ├── script2.sh
    └── helper.js

Lignes directrices pour l'écriture de scripts

1. Autonomie

Les scripts doivent être aussi autonomes que possible ou documenter clairement leurs dépendances.

Exemple de script autonome

#!/usr/bin/env python3
"""
Script d'extraction de texte PDF

Dépendance : pip install pdfplumber
Exécuter : python scripts/extract_pdf.py input.pdf
"""

import sys
import pdfplumber

def extract_text_from_pdf(pdf_path):
    """Extraire le texte d'un fichier PDF"""
    with pdfplumber.open(pdf_path) as pdf:
        text = ""
        for page in pdf.pages:
            text += page.extract_text() or ""
    return text

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Utilisation : python extract_pdf.py <fichier pdf>")
        sys.exit(1)

    pdf_path = sys.argv[1]
    text = extract_text_from_pdf(pdf_path)
    print(text)

2. Gestion claire des erreurs

Les scripts doivent fournir des messages d'erreur utiles pour aider les agents à comprendre ce qui s'est mal passé.

Exemple de gestion des erreurs

import sys

def main():
    if len(sys.argv) < 2:
        print("Erreur : argument obligatoire manquant", file=sys.stderr)
        print("Utilisation : python script.py <fichier d'entrée> [fichier de sortie]", file=sys.stderr)
        sys.exit(1)

    input_file = sys.argv[1]

    try:
        # Exécuter la logique principale
        process_file(input_file)
    except FileNotFoundError:
        print(f"Erreur : fichier {input_file} introuvable", file=sys.stderr)
        sys.exit(1)
    except PermissionError:
        print(f"Erreur : aucune permission pour lire le fichier {input_file}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Erreur : une erreur inconnue s'est produite lors du traitement du fichier : {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

3. Gestion des cas limites

Les scripts doivent gérer élégamment divers cas limites au lieu de planter.

Exemple de gestion des cas limites

def validate_input(text):
    """Vérifier si l'entrée est valide"""
    if not text:
        return False, "L'entrée ne peut pas être vide"

    if len(text) > 10000:
        return False, "La longueur de l'entrée dépasse la limite (max 10000 caractères)"

    return True, ""

# Utiliser la validation
is_valid, error_msg = validate_input(user_input)
if not is_valid:
    print(f"Échec de la validation : {error_msg}")
    sys.exit(1)

Référencement des scripts dans SKILL.md

Lorsqu'une compétence doit exécuter un script, décrivez dans SKILL.md comment l'appeler.

Référencement des scripts :

## PDF 文本提取

使用脚本提取 PDF 中的文本：

```bash
python scripts/extract_pdf.py input.pdf
```

脚本会从 input.pdf 提取所有文本并输出到标准输出。

如果需要将结果保存到文件：

```bash
python scripts/extract_pdf.py input.pdf > output.txt
```

Remarque : utilisez des chemins relatifs au répertoire racine de la compétence lors du référencement des scripts.

Langages de script pris en charge

Les langages de script pris en charge dépendent de l'implémentation d'agent que vous utilisez. Les options courantes incluent :

Langage Description
Python Le choix le plus couramment utilisé, puissant et facile à écrire
Bash Adapté aux opérations système et aux outils en ligne de commande
JavaScript Adapté aux tâches liées au Web

Astuce : lors du choix d'un langage de script, tenez compte de l'environnement d'exécution de l'utilisateur cible. En cas de doute, Python est le choix le plus sûr.

Exemple complet : compétence de traitement PDF

Examinons un exemple complet montrant comment combiner SKILL.md et des scripts :

Structure de la compétence

pdf-tool/
├── SKILL.md
└── scripts/
    ├── extract.py
    ├── fill_form.py
    └── merge.py

Contenu de SKILL.md :

---
name: pdf-tool
description: 处理 PDF 文件，包括提取文本、填写表单、合并文件。使用场景：处理 PDF、提取文本、填写表单、合并 PDF.
---

## 提取 PDF 文本

从 PDF 文件中提取文本内容：

```bash
python scripts/extract.py input.pdf
```

输出是提取的纯文本内容。

## 填写 PDF 表单

使用 JSON 数据填写 PDF 表单：

```bash
python scripts/fill_form.py input.pdf data.json output.pdf
```

data.json 格式：
```json
{
  "field_name": "字段值",
  "another_field": "另一个值"
}
```

## 合并 PDF

将多个 PDF 文件合并为一个：

```bash
python scripts/merge.py output.pdf input1.pdf input2.pdf input3.pdf
```

## 依赖安装

需要安装 pdfplumber 和 PyPDF2：

```bash
pip install pdfplumber PyPDF2
```

Deux modes d'utilisation

Il existe deux façons d'utiliser du code dans une Skill :

Méthode Scénario applicable Nécessité d'un répertoire scripts/
Commande ponctuelle Il suffit d'appeler des outils existants, aucune logique personnalisée n'est requise Non nécessaire
Script autonome Logique complexe qui doit être réutilisée Nécessaire

Commandes ponctuelles

Lorsque les outils de gestion de paquets existants répondent déjà aux besoins, vous pouvez les référencer directement dans les instructions de SKILL.md sans créer de répertoire scripts/.

Voici les méthodes d'exécution courantes dans chaque écosystème de langage :

uvx（Python）

uvx est la commande d'exécution d'outils fournie avec uv. Elle exécute des paquets Python dans un environnement isolé et, grâce à une mise en cache agressive, les exécutions répétées sont quasiment instantanées.

Exemple

# Exécuter la version spécifiée de ruff pour vérifier le code
uvx ruff@0.8.0 check .

# Exécuter la version spécifiée de black pour formater le code
uvx black@24.10.0 .

pipx（Python）

pipx est une alternative mature à uvx et peut être installé via les gestionnaires de paquets système (p. ex.,brew install pipx）。

Exemple

# Exécuter la version spécifiée de black
pipx run 'black==24.10.0' .

# Exécuter la version spécifiée de ruff
pipx run '[email protected]' check .

npx（Node.js）

npx est fourni avec npm et télécharge et exécute des paquets npm à la demande.

Exemple

# Exécuter la vérification ESLint
npx eslint@9 --fix .

# Créer un projet avec Vite
npx create-vite@6 my-app

go run（Go）

La commande intégrée de Go pour exécuter des outils compile et exécute directement des paquets distants.

Exemple

# Exécuter goimports pour formater les imports
go run golang.org/x/tools/cmd/goimports@v0.28.0 .

# Exécuter la vérification golangci-lint
go run github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 run

Recommandations pour l'écriture de commandes à exécution unique : Fixez les numéros de version (par ex.,npx [email protected]) afin de garantir un comportement cohérent ; déclarez les prérequis dans SKILL.md (par ex., "Node.js 18+ requis") ; lorsque les commandes deviennent complexes, extrayez-les dans le répertoire scripts/.

Référencement des scripts dans SKILL.md

Utilisez des chemins partant de la racine du répertoire Skillchemins relatifspour référencer les fichiers empaquetés.

L'agent résoudra automatiquement ces chemins ; il n'est pas nécessaire d'utiliser des chemins absolus.

Tout d'abord, listez les scripts disponibles dans SKILL.md :

Exemple

## Scripts disponibles

- **`scripts/validate.sh`** — Valider les fichiers de configuration
- **`scripts/process.py`** — Traiter les données d'entrée
- **`scripts/report.py`** — Générer des rapports d'analyse

Ensuite, référencez-les dans les étapes d'opération :

Exemple

## Flux de travail opérationnel

1. Exécutez le script de validation :
   ```bash
   bash scripts/validate.sh "$INPUT_FILE"
   ```

2. Traiter les données :
   ```bash
   python3 scripts/process.py --input results.json
   ```

Les chemins d'exécution des scripts sont relatifs à la racine du répertoire Skill, car l'Agent exécute les commandes depuis le répertoire Skill. Cela s'applique également aux fichiers auxiliaires tels que references/*.md.

Scripts autonomes

Lorsque vous avez besoin d'une logique réutilisable, vous pouvez empaqueter des scripts dans lescripts/répertoire et déclarer les dépendances dans le script.

L'Agent peut l'exécuter avec une seule commande, sans étapes d'installation supplémentaires.

Script Python autonome (PEP 723)

PEP 723 définit un format standard pour déclarer les dépendances à l'intérieur des scripts Python.

Utiliser# ///marqueurs pour encadrer la déclaration de dépendances au format TOML :

Exemple : Script Python autonome

# /// script
# dependencies = [
# "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

# Exemple de contenu HTML
html = '<html><body><h1>Welcome</h1><p class="info">EXAMPLE Test</p></body></html>'

# Analyser le HTML avec BeautifulSoup
soup = BeautifulSoup(html, "html.parser")

# Extraire le texte du paragraphe avec class="info"
info_text = soup.select_one("p.info").get_text()
print(info_text)

Comment exécuter :

Exemple

# Exécuter avec uv (recommandé)
uv run scripts/extract.py

# Exécuter avec pipx
pipx run scripts/extract.py
EXAMPLE 测试

Script Deno autonome

Deno utilisenpm:etjsr:spécificateurs d'import pour atteindre l'autonomie :

Exemple : Script Deno autonome

#!/usr/bin/env -S deno run

import * as cheerio from "npm:[email protected]";

const html = `<html><body><h1>Bienvenue</h1><p class="info">EXEMPLE Test</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());

Exemple

deno run scripts/extract.ts

Script autonome Bun

Lorsque Bun n'a pas denode_modulesrépertoire, il installe automatiquement les paquets manquants :

Exemple : script autonome Bun

#!/usr/bin/env bun

import * as cheerio from "[email protected]";

const html = `<html><body><h1>Bienvenue</h1><p class="info">EXEMPLE Test</p></body></html>`;
const $ = cheerio.load(html);
console.log($("p.info").text());

Exemple

bun run scripts/extract.ts

Script autonome Ruby

Ruby utilisebundler/inlinepour déclarer les dépendances de gems dans le script :

Exemple : script autonome Ruby

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'nokogiri'
end

html = '<html><body><h1>Bienvenue</h1><p class="info">EXEMPLE Test</p></body></html>'
doc = Nokogiri::HTML(html)
puts doc.at_css('p.info').text

Exemple

ruby scripts/extract.rb

Points clés pour la conception de scripts pour agents

L'Agent détermine ses prochaines actions en lisant stdout et stderr, donc la conception des scripts doit prendre en compte les caractéristiques d'utilisation de l'Agent.

Éviter les invites interactives

Il s'agit d'une exigence absolue. L'Agent s'exécute dans un shell non interactif et ne peut pas répondre aux invites TTY, aux boîtes de dialogue de mot de passe ou aux menus de confirmation.

Toutes les entrées doivent être passées via des arguments de ligne de commande, des variables d'environnement ou stdin.

Exemple : Approche incorrecte vs Approche correcte

# Incorrect : va se bloquer en attendant une entrée
$ python scripts/deploy.py
Environnement cible : _

# Correct : message d'erreur clair et conseils
$ python scripts/deploy.py
Erreur : --env est requis. Options : development, staging, production.
Utilisation : python scripts/deploy.py --env staging --tag v1.2.3

Fournissez une documentation --help

--helpLa sortie est le principal moyen pour l'Agent de comprendre l'interface du script.

Incluez une brève description, les paramètres disponibles et des exemples d'utilisation :

Exemple : bonne sortie --help

Utilisation : scripts/process.py [OPTIONS] INPUT_FILE

Traiter les données d'entrée et générer un rapport de synthèse.

Options :
  --formatFORMAT Format de sortie : json, csv, table(Par défaut : json)
  --outputFILE Écrire la sortie dans un fichier au lieu de stdout
  --verboseAfficher les informations de progression sur stderr

Exemples :
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

Écrire des messages d'erreur utiles

Lorsque l'Agent voit un message d'erreur, il ajuste sa stratégie en conséquence ; plus le message est spécifique, plus il est facile pour l'Agent de se corriger.

Exemple

# Mauvais message d'erreur
Erreur : entrée non valide

# Bon message d'erreur
Erreur : --format doit être l'un des éléments suivants : json, csv, table.
       Reçu : "xml"

Utiliser une sortie structurée

Préférez les formats structurés tels que JSON, CSV et TSV pour la sortie, plutôt que du texte libre.

Les formats structurés peuvent être consommés à la fois par l'Agent et par les outils standard (jq, cut, awk), ce qui les rend faciles à combiner.

Exemple

# Non recommandé : le texte aligné est difficile à analyser par programmation
NAME STATUS CREATED
my-service running   2025-01-15

# Recommandé : format JSON avec des limites de champs claires
{"name": "my-service", "status": "running", "created": "2025-01-15"}

Envoyez les données structurées vers stdout, et les messages de progression et les informations de diagnostic vers stderr. Ainsi, l'Agent obtient une sortie propre et analysable tout en pouvant consulter les informations de diagnostic si nécessaire.

Autres suggestions de conception de script

Suggestion Description
Idempotence L'Agent peut réessayer les commandes. "Créer s'il n'existe pas" est plus sûr que "créer et échouer en cas de doublons"
Contraintes d'entrée Rejeter les entrées ambiguës avec une erreur claire, plutôt que de deviner l'intention de l'utilisateur
Prise en charge du dry-run Pour les opérations destructives ou avec état, fournir un--dry-rundrapeau pour permettre à l'Agent de prévisualiser l'opération
Codes de sortie explicites Utiliser des codes de sortie différents pour différents types d'échec (introuvable, argument invalide, échec d'authentification, etc.)
Taille de sortie prévisible Afficher un résumé par défaut et fournir--offsetd'autres paramètres afin que l'Agent puisse obtenir plus d'informations selon ses besoins.
Valeurs par défaut sûres Les opérations destructives doivent exiger un drapeau de confirmation explicite (--confirm、--force）

Exemple complet de script Skill

Voici une structure de répertoire Skill complète contenant des scripts :

Exemple

csv-analyzer/
├── SKILL.md              # Fichier d'instructions principal
├── scripts/
│ ├── overview.py       # Script d'aperçu des données
│ ├── summary.py        # Script de résumé statistique
│ └── validate.py       # Script de validation des données
├── references/
│ └── api-errors.md     # Référence des erreurs API
└── assets/
    └── report-template.md  # Modèle de rapport

Le contenu correspondant de SKILL.md :

Exemple

---
name: csv-analyzer
description: >
Analyser des fichiers de données CSV et tabulaires. Lorsque l'utilisateur a des fichiers CSV, TSV ou Excel
et souhaite explorer, transformer ou visualiser des données, utilisez ceci.
---

# Analyse de données CSV

## Scripts disponibles

- **`scripts/overview.py`** — Affiche l'aperçu des données (nombre de lignes, noms des colonnes, types)
- **`scripts/summary.py`** — Génère un résumé statistique
- **`scripts/validate.py`** — Valide la qualité des données

## Flux de travail

1. Commencez par exécuter le script overview pour comprendre la structure des données :
   ```bash
   uv run scripts/overview.py input.csv
   ```

2. Générez le résumé statistique :
   ```bash
   uv run scripts/summary.py input.csv --output summary.json
   ```

3. Valider la qualité des données :
   ```bash
   uv run scripts/validate.py input.csv
   ```

## Remarques

- Pour les fichiers volumineux, utilisez le paramètre `--chunk-size` pour traiter par blocs
- Pour les fichiers CSV chinois, essayez le paramètre `--encoding gbk`

Distribution des scripts et dépendances

Si vos scripts nécessitent des dépendances externes, vous disposez de plusieurs options :

1. Documenter les dépendances dans SKILL.md

La façon la plus simple est de consigner les dépendances requises dans SKILL.md.

2. Utiliser des environnements virtuels

Pour les projets complexes, vous pouvez créer un environnement virtuel.

3. Utiliser Docker

Si un environnement d'exécution complet est nécessaire, vous pouvez utiliser un conteneur Docker.

Remarque : Assurez-vous que les scripts peuvent s'exécuter dans l'environnement cible. Avant d'écrire des scripts, comprenez l'environnement d'exécution de l'utilisateur cible.

Résumé

Dans cette section, nous avons appris à utiliser des scripts pour étendre les fonctionnalités de Skill :

  • Placez les scripts dans le répertoire scripts/
  • Les scripts doivent être autonomes et avoir une gestion claire des erreurs
  • Utilisez des chemins relatifs lorsque vous référencez des scripts dans SKILL.md
  • Assurez-vous que les scripts peuvent s'exécuter dans l'environnement cible
Autres extensions