### Skill Configuration Example

Source: https://agentskills.io/skill-creation/optimizing-descriptions

This example shows a typical configuration for a skill, including its name, query file, and the number of runs. Ensure the query file path is correct for your setup.

```json
{
  "queries_file": "./queries.json",
  "skill_name": "my-skill",
  "runs": 3
}
```

--------------------------------

### Script Usage Example

Source: https://agentskills.io/skill-creation/using-scripts

This example demonstrates the command-line usage for a Python script, including its purpose, available options, and example invocations. It's useful for understanding how to interact with scripts from the command line.

```text
Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
 --format FORMAT Output format: json, csv, table (default: json)
 --output FILE Write output to FILE instead of stdout
 --verbose Print progress to stderr

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

--------------------------------

### Documenting Script Usage with --help

Source: https://agentskills.io/skill-creation/using-scripts

An example of how a script's `--help` output should be formatted to provide agents with necessary information about its interface, including descriptions, flags, and usage examples.

```text
Usage: ./my_script.sh [options]

This script does amazing things with data.

Options:
  --input FILE      Path to the input data file (required)
  --output FILE     Path to the output file (optional)
  --verbose         Enable verbose logging
  --help            Display this help message and exit

Examples:
  ./my_script.sh --input data.csv --output results.txt
  ./my_script.sh --input data.json --verbose

```

--------------------------------

### SKILL.md Minimal Frontmatter Example

Source: https://agentskills.io/specification

Provides a minimal example of the YAML frontmatter required for a SKILL.md file. This includes the essential 'name' and 'description' fields.

```markdown
---
name: "example-skill"
description: "An example skill."
---

```

--------------------------------

### Skill Execution Workflow Example

Source: https://agentskills.io/skill-creation/best-practices

This example demonstrates a typical multi-step workflow for a skill, including analysis, mapping, validation, filling, and verification. Each step is executed sequentially using specified scripts.

```markdown
-
 [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
-
 [ ] Step 2: Create field mapping (edit `fields.json`)
-
 [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)
-
 [ ] Step 4: Fill the form (run `scripts/fill_form.py`)
-
 [ ] Step 5: Verify output (run `scripts/verify_output.py`)
```

--------------------------------

### Eval File Structure Example

Source: https://agentskills.io/skill-creation/evaluating-skills

This example illustrates the typical directory and file structure for an evaluation, including input files, output directories, and generated statistics.

```text
├── evals.json
│ ├── timing.json
│ └── grading.json
├── eval-clean-missing-emails/
│ ├── with_skill/
│ │ ├── outputs/
│ │ ├── timing.json
│ │ └── grading.json
│ └── without_skill/
│ ├── outputs/
│ ├── timing.json
│ └── grading.json
└── benchmark.json # Aggregated statistics
```

--------------------------------

### Example of a Good Prompt

Source: https://agentskills.io/skill-creation/optimizing-descriptions

This example shows a prompt that includes specific details like file paths, personal context, and casual language, making it more realistic and likely to trigger the correct skill.

```plaintext
"~/Downloads/report_final_v2.xlsx"
```

```plaintext
"my manager asked me to..."
```

--------------------------------

### Example Agent Instruction for Skill Evaluation

Source: https://agentskills.io/skill-creation/evaluating-skills

Provides an example of instructions given to an agent to execute a task using a specific skill, including the skill path, task description, input files, and output directory.

```text
Execute this task:
- Skill path: /path/to/csv-analyzer
- Task: I have a CSV of monthly sales data in data/sales_2025.csv.
 Can you find the top 3 months by revenue and make a bar chart?
- Input files: evals/files/sales_2025.csv
- Save outputs to: csv-analyzer-workspace/iteration-1/
```

--------------------------------

### Install Cheerio for HTML Parsing

Source: https://agentskills.io/skill-creation/using-scripts

Use npm to install the Cheerio library, a fast, flexible, and lean implementation of core jQuery designed specifically for the server.

```shellscript
npm install cheerio@1.0.0
```

--------------------------------

### Skill Directory Structure Example

Source: https://agentskills.io/specification

A skill is a directory that must contain at least a SKILL.md file. This example shows a basic structure.

```markdown
SKILL.md
references/REFERENCE.md
```

--------------------------------

### SQL Query Generation Example

Source: https://agentskills.io/skill-creation/best-practices

This example demonstrates how to construct a SQL query based on user input, including filtering and aggregation. It outlines a step-by-step process for reading schema, joining tables, applying filters, and aggregating data.

```markdown
```
// Example: Generate a SQL query to find the total amount for a customer in a specific region.
// This is a reusable method that works for any analytical query.

1. Read the schema from `references/schema.yaml` to find relevant tables
2. Join tables using the `_id` foreign key convention
3. Apply any filters from the user's request as WHERE clauses
4. Aggregate numeric columns as needed and format as a markdown table
```
```

--------------------------------

### Install Cheerio Package

Source: https://agentskills.io/skill-creation/using-scripts

Installs the Cheerio package using npm. This command should be run in your project's terminal to make the library available for use.

```shellscript
npm install cheerio
```

--------------------------------

### SKILL.md script execution example

Source: https://agentskills.io/skill-creation/using-scripts

Instruct the agent to run bundled scripts using bash and python3, passing arguments.

```markdown
## Workflow

1. Run the validation script:
   ```bash
   bash scripts/validate.sh "$INPUT_FILE"
   ```

2. Process the results:
   ```bash
   python3 scripts/process.py --input results.json
   ```

```

--------------------------------

### YAML Configuration Example

Source: https://agentskills.io/specification

This snippet shows a valid YAML configuration for an agent skill, including the 'name' field.

```yaml
name: pdf-processing

```

```yaml
name: data-analysis

```

```yaml
name: web-scraping

```

--------------------------------

### Form Processing Workflow Checklist Example

Source: https://agentskills.io/llms-full.txt

An example of a checklist for a multi-step form processing workflow, outlining the steps and associated scripts.

```markdown
## Form processing workflow

Progress:
- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
- [ ] Step 2: Create field mapping (edit `fields.json`)
- [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)
- [ ] Step 4: Fill the form (run `scripts/fill_form.py`)
- [ ] Step 5: Verify output (run `scripts/verify_output.py`)
```

--------------------------------

### Example of a Go command in a skill

Source: https://agentskills.io/skill-creation/using-scripts

This snippet shows how a Go command might be represented within a skill's configuration, including the command and its arguments.

```javascript
sName: \
```

--------------------------------

### Procedure vs. Declaration Example

Source: https://agentskills.io/llms-full.txt

Illustrates the difference between a specific, declarative instruction and a reusable, procedural approach for an analytical task.

```markdown
<!-- Specific answer — only useful for this exact task -->
Join the `orders` table to `customers` on `customer_id`, filter where
`region = 'EMEA'`, and sum the `amount` column.

<!-- Reusable method — works for any analytical query -->
1. Read the schema from `references/schema.yaml` to find relevant tables
2. Join tables using the `_id` foreign key convention
3. Apply any filters from the user's request as WHERE clauses
4. Aggregate numeric columns as needed and format as a markdown table
```

--------------------------------

### Poor 'description' field example

Source: https://agentskills.io/llms-full.txt

Avoid vague descriptions. This example is too brief and lacks specific keywords for effective agent task identification.

```yaml
description: Helps with PDFs.
```

--------------------------------

### Markdown Reference File Example

Source: https://agentskills.io/specification

Example of a markdown file used for detailed technical reference within an agent skill. Keep these files focused and smaller for efficient loading.

```markdown
REFERENCE.md
```

```markdown
FORMS.md
```

```markdown
finance.md
```

```markdown
legal.md
```

--------------------------------

### Skill Compatibility Example

Source: https://agentskills.io/specification

Indicates specific environment requirements for the skill. Use if the skill needs particular products, system packages, or network access.

```yaml
compatibility: Must be 1-500 characters if provided
Should only be included if your skill has specific environment requirements
Can indicate intended product, required system packages, network access needs, etc.
```

--------------------------------

### Output Format Template Example

Source: https://agentskills.io/skill-creation/best-practices

Provide a markdown template for the agent to produce output in a specific format. This is more reliable than prose descriptions.

```markdown
## Report structure

Use this template, adapting sections as needed for the specific analysis:

```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```
```

--------------------------------

### Create Checklists for Multi-Step Workflows

Source: https://agentskills.io/skill-creation/best-practices

Implement checklists in Markdown to guide agents through multi-step processes. This helps track progress and manage dependencies.

```markdown
## Form processing workflow

Progress:
- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
- [ ] Step 2: Create field mapping (edit `fields.json`)
- [ ] Step 3: Validate mapping (run `
```

--------------------------------

### Markdown File Reference Example

Source: https://agentskills.io/specification

Demonstrates how to reference other files within a skill using relative paths in markdown. This is crucial for agents loading skills progressively.

```markdown
See [\
```

--------------------------------

### YAML Example: Before and After Description

Source: https://agentskills.io/skill-creation/optimizing-descriptions

Illustrates the change in a skill's description field before and after optimization. This is a common pattern in `SKILL.md` files.

```yaml
# Before
description: Process CSV files.

# After
description: Process CSV files, handling various delimiters and encodings.
```

--------------------------------

### Valid Skill Name Example

Source: https://agentskills.io/specification

Demonstrates a valid skill name. Skill names should be descriptive and follow specific naming conventions.

```yaml
name: code-review
```

--------------------------------

### Good 'description' field example

Source: https://agentskills.io/llms-full.txt

A comprehensive 'description' should detail the skill's function and usage context, including keywords for agent identification.

```yaml
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
```

--------------------------------

### Saving Feedback as JSON

Source: https://agentskills.io/skill-creation/evaluating-skills

This example shows how to structure feedback for a test case, saving it as a JSON file alongside evaluation directories for later review.

```json
{
  "test_case_name": "example_test_case",
  "feedback": "The model correctly identified the sentiment but missed the nuance in the second sentence."
}
```

--------------------------------

### Markdown for Database Migration Steps

Source: https://agentskills.io/skill-creation/best-practices

Use markdown to define a prescriptive sequence for a database migration. This example indicates that a specific order of operations is required.

```markdown
## Database migration

Run exactly this sequence:
```

--------------------------------

### Valid 'name' field examples

Source: https://agentskills.io/llms-full.txt

The 'name' field must be lowercase alphanumeric with hyphens, not starting or ending with a hyphen, and without consecutive hyphens.

```yaml
name: pdf-processing
```

```yaml
name: data-analysis
```

```yaml
name: code-review
```

--------------------------------

### Check if a Skill Was Invoked

Source: https://agentskills.io/llms-full.txt

This bash function checks if a specific skill was invoked by an LLM query. It uses `claude` to get JSON output and `jq` to parse the tool usage. Ensure `SKILL_NAME` is set and `jq` is installed.

```bash
check_triggered() {
  local query="$1"
  claude -p "$query" --output-format json 2>/dev/null \
    | jq -e --arg skill "$SKILL_NAME" \
      'any(.messages[].content[]; .type == "tool_use" and .name == "Skill" and .input.skill == $skill)' \
      > /dev/null 2>&1
}
```

--------------------------------

### Helpful `--help` output for scripts

Source: https://agentskills.io/llms-full.txt

Include a brief description, available flags, and usage examples in your script's `--help` output. This is the primary way an agent learns your script's interface.

```bash
Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
  --format FORMAT    Output format: json, csv, table (default: json)
  --output FILE      Write output to FILE instead of stdout
  --verbose          Print progress to stderr

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

--------------------------------

### Deploy Python Script with Arguments

Source: https://agentskills.io/skill-creation/using-scripts

Example of deploying a Python script with required and optional arguments. Ensure all necessary flags like `--env` are provided for successful execution.

```text
Error: --env is required. Options: development, staging, production.
Usage: python scripts/deploy.py --env staging --tag v1.2.3
```

--------------------------------

### Install and Use pipx

Source: https://agentskills.io/skill-creation/using-scripts

pipx installs and runs Python packages in isolated environments. It can be installed via package managers like apt or brew.

```shellscript
apt install pipx
```

```shellscript
brew install pipx
```

--------------------------------

### Example of a Bad Prompt

Source: https://agentskills.io/skill-creation/optimizing-descriptions

This example demonstrates a prompt that is too generic and lacks the specific details needed for a skill to be triggered appropriately.

```plaintext
"can you write a python script that reads a csv and uploads each row to our postgres database"
```

--------------------------------

### Valid Description Field Example

Source: https://agentskills.io/specification

Provides an example of a well-formed description for a skill. The description should be informative and include relevant keywords.

```yaml
description: |-
  This skill can process PDF files to extract text and metadata.
  Use this skill when you need to analyze the content of PDF documents.
```

--------------------------------

### Valid Description Field Example

Source: https://agentskills.io/specification

Provides an example of a well-formed description for an agent skill. The description should be detailed and include relevant keywords.

```yaml
description: This skill can process PDF files, extracting text and metadata. Use it when you need to analyze or convert PDF documents.
```

--------------------------------

### Invalid 'name' field examples

Source: https://agentskills.io/llms-full.txt

These examples show common errors in the 'name' field, such as uppercase letters, leading hyphens, and consecutive hyphens.

```yaml
name: PDF-Processing  # uppercase not allowed
```

```yaml
name: -pdf  # cannot start with hyphen
```

```yaml
name: pdf--processing  # consecutive hyphens not allowed
```

--------------------------------

### SKILL.md Frontmatter with Optional Fields

Source: https://agentskills.io/specification

Demonstrates the use of optional fields such as 'license' and 'metadata' in addition to the required 'name' and 'description'. Use 'metadata' for custom key-value pairs.

```yaml
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---
```

--------------------------------

### Agent Script Input Methods

Source: https://agentskills.io/skill-creation/using-scripts

Illustrates how agents expect scripts to receive input. Avoid interactive prompts; instead, use command-line flags, environment variables, or stdin. This example shows a 'bad' case that hangs waiting for input.

```text
# Bad: hangs waiting for input
$ python scripts/deploy.py
```

--------------------------------

### Create Vite project with bunx

Source: https://agentskills.io/skill-creation/using-scripts

Use bunx to run the create-vite scaffolding tool with a specific version in a Bun environment.

```bash
bunx create-vite@6 my-app
```

--------------------------------

### Assertion Example: Valid JSON Output

Source: https://agentskills.io/skill-creation/evaluating-skills

This is an example of a verifiable assertion for skill output. It checks if the generated file adheres to the JSON format, which can be programmatically verified.

```string
"The output file is valid JSON"
```

--------------------------------

### Markdown Skill Definition Example

Source: https://agentskills.io/skill-creation/best-practices

This markdown snippet demonstrates how to define a skill, including a title and a description. It shows an example of what to include and what to omit to optimize context for the agent.

```markdown
<!-- Too verbose — the agent already knows what PDFs are -->
## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
```

--------------------------------

### Helpful Error Message Example

Source: https://agentskills.io/skill-creation/using-scripts

Provides an example of a clear and informative error message for a script. This helps agents understand what went wrong, what was expected, and how to correct the issue, improving retry logic.

```text
Error: --format must be one of: json, csv, table.
 Received: "xml"
```

--------------------------------

### Instructions for LLM Agent Evaluation Run

Source: https://agentskills.io/llms-full.txt

Provide the agent with specific instructions for executing a task, including the skill path, the task description, input files, and the output directory. For baseline runs, omit the skill path and save to 'without_skill/outputs/'.

```text
Execute this task:
- Skill path: /path/to/csv-analyzer
- Task: I have a CSV of monthly sales data in data/sales_2025.csv.
  Can you find the top 3 months by revenue and make a bar chart?
- Input files: evals/files/sales_2025.csv
- Save outputs to: csv-analyzer-workspace/iteration-1/eval-top-months-chart/with_skill/outputs/
```

--------------------------------

### SQL Query for Joining Tables

Source: https://agentskills.io/skill-creation/best-practices

This SQL snippet demonstrates joining the 'orders' table to the 'customers' table. It's an example of a specific query rather than a general procedure.

```sql
Join the "orders" table to "customers" on "customer_id"
```

--------------------------------

### Declaring a script in SKILL.md

Source: https://agentskills.io/skill-creation/using-scripts

Example of how to list a specific script, like 'scripts/validate.sh', in the SKILL.md file.

```markdown
- 

```

--------------------------------

### Gemfile Version Pinning

Source: https://agentskills.io/skill-creation/using-scripts

Example of pinning a specific version of a gem in a Gemfile. This is crucial for reproducible builds.

```ruby
gem 'nokogiri', '~> 1.16'
```

--------------------------------

### Workspace Structure for Skill Evaluation

Source: https://agentskills.io/skill-creation/evaluating-skills

This text-based example illustrates the directory structure for organizing skill evaluation results. It shows how to separate skill files from evaluation workspaces, with nested directories for iterations, test cases, and 'with_skill'/'without_skill' runs, including outputs and timing data.

```text
csv-analyzer/\n├── SKILL.md\n└── evals/\n └── evals.json\ncsv-analyzer-workspace/\n└── iteration-1/\n ├── eval-top-months-chart/\n │ ├── with_skill/\n │ │ ├── outputs/ # Files produced by the run\n │ │ ├── timing.json # Tokens and duration\n │ │ └── grading.json # Assertion results\n │ └── without_skill/\n │ ├── outputs/\n │ ├── timing.json\n │ └── grading.json\n └── eval-another-test-case/\n ├── with_skill/\n │ ├── outputs/\n │ ├── timing.json\n │ └── grading.json\n └── without_skill/\n ├── outputs/\n ├── timing.json\n └── grading.json
```

--------------------------------

### Markdown for Tool Selection with Default

Source: https://agentskills.io/skill-creation/best-practices

Demonstrates how to present tool options in markdown, favoring a specific default (pdfplumber) and mentioning alternatives for different use cases (scanned PDFs).

```markdown
<!-- Too many options -->
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

<!-- Clear default with escape hatch -->
Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
```

--------------------------------

### Adding Assertions to evals.json

Source: https://agentskills.io/skill-creation/evaluating-skills

Example of how to structure the `evals.json` file to include specific assertions for a skill, such as the 'csv-analyzer' skill.

```json
{
 "skill_name": "csv-analyzer",
 "evals": [
 {
 "id": 1,
 "prompt": 
```

--------------------------------

### Example Skill Prompt Structure

Source: https://agentskills.io/skill-creation/evaluating-skills

This JSON structure represents a skill prompt, including an ID, the user's prompt, the expected output, and any associated files. Use this structure to define and test your skills.

```json
{
  "id": "2",
  "prompt": "there's a csv in my downloads called customers.csv, some rows have missing emails — can you clean it up and tell me how many were missing?",
  "expected_output": "A cleaned CSV with missing emails handled, plus a count of how many were missing.",
  "files": [
    "evals/files/customers.csv"
  ]
}
```

--------------------------------

### Optional 'allowed-tools' field example

Source: https://agentskills.io/llms-full.txt

The 'allowed-tools' field lists pre-approved tools for the skill to use. This is an experimental feature.

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

--------------------------------

### Bun script with Cheerio

Source: https://agentskills.io/skill-creation/using-scripts

Example of a Bun script that imports and uses the Cheerio library for HTML parsing. Bun auto-installs missing packages at runtime. Pin versions directly in the import path.

```typescript
#!/usr/bin/env bun

import * as cheerio from "cheerio@1.0.0";

const html = `<html><body><h1>Welcome</h1><p class="info">This is a test.</p></body></html>`;
```

--------------------------------

### Create Vite project with npx

Source: https://agentskills.io/skill-creation/using-scripts

Use npx to run the create-vite scaffolding tool with a specific version.

```bash
npx create-vite@6 my-app
```

--------------------------------

### Prescriptive Database Migration Command

Source: https://agentskills.io/skill-creation/best-practices

Use this markdown example to define a strict sequence for a database migration. It specifies the exact command and flags to use, discouraging modifications.

```markdown
## Database migration

Run exactly this sequence:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.
```

--------------------------------

### Run npm packages with bunx

Source: https://agentskills.io/llms-full.txt

Use bunx, Bun's equivalent of npx, for running npm packages. It's a drop-in replacement suitable for Bun-based environments.

```bash
bunx eslint@9 --fix .
bunx create-vite@6 my-app
```

--------------------------------

### Run Black with uvx

Source: https://agentskills.io/skill-creation/using-scripts

Use uvx to run the black formatter with a specific version. It is not bundled with Python and requires a separate installation.

```shellscript
uvx black==24.10.0 .
```