SKILL.md Format

Complete specification for the skill file format.

Overview

A SKILL.md file consists of two parts:

YAML frontmatter — Metadata, contracts, capabilities, and tests
Markdown body — Instructions for AI assistants

Required Fields

---
name: my-skill           # Skill name (lowercase, hyphens)
version: 1.0.0          # Semantic version
description: Brief desc  # One-line description
author: username        # Publisher username
---

Optional Metadata

---
name: my-skill
version: 1.0.0
description: Brief description
author: username

# Optional fields
license: MIT
keywords:
  - keyword1
  - keyword2
repository: https://github.com/user/repo
homepage: https://example.com
---

Field Reference

Field	Type	Description
license	string	SPDX license identifier
keywords	string[]	Search keywords
repository	string	Source code URL
homepage	string	Project website

Contracts (Inputs/Outputs)

Define expected inputs and outputs for your skill:

contract:
  inputs:
    - name: file_path
      type: file
      required: true
      description: Path to the PDF file
    - name: pages
      type: string
      description: Page range (e.g., "1-5")
  outputs:
    - name: text
      type: string
      description: Extracted text content
    - name: metadata
      type: object
      description: Document metadata

Supported Types

stringnumberbooleanfilearrayobjectanycodeurl

Capabilities

Declare permissions your skill requires:

capabilities:
  - capability: file:read
    reason: To read PDF files from disk
    constraints:
      paths: ["*.pdf"]
  - capability: network:https
    reason: To fetch data from APIs
    constraints:
      hosts: ["api.example.com"]
  - capability: shell:execute
    reason: To run conversion commands
    optional: true

Available Capabilities

Capability	Description
file:read	Read files from filesystem
file:write	Write files to filesystem
network:https	Make HTTPS requests
shell:execute	Execute shell commands
database:read	Read from databases
database:write	Write to databases
env:read	Read environment variables

Tests

Define test cases to verify your skill:

tests:
  - name: basic-extraction
    input:
      file_path: "test.pdf"
      pages: "1"
    expect:
      success: true
      output:
        text: "Expected text content"

  - name: invalid-file
    input:
      file_path: "nonexistent.pdf"
    expect:
      success: false

Run tests with aster test.

Composition

Extend or include other skills:

composition:
  extends:
    skill: "@base/document-tools"
    version: "^1.0.0"
  includes:
    - skill: "@utils/text-processing"
      alias: textUtils
    - skill: "@utils/file-handling"
      alias: fileUtils

Markdown Body

After the frontmatter, write instructions for AI assistants:

---
# ... frontmatter ...
---

# PDF Tools

Extract text, tables, and images from PDF documents.

## Usage

When the user wants to work with a PDF file:

1. Ask for the file path if not provided
2. Determine the desired operation (text, tables, images)
3. Execute the appropriate extraction
4. Return results in a structured format

## Operations

### Extract Text
Extract all text content while preserving layout.

### Extract Tables
Parse tables into structured JSON data.

## Examples

User: "Extract the text from report.pdf"
Action: Read the PDF and return extracted text

User: "Get all tables from data.pdf pages 2-5"
Action: Extract tables from specified pages

## Error Handling

- If the file doesn't exist, ask the user to verify the path
- If the PDF is encrypted, inform the user and ask for password
- If extraction fails, provide a clear error message

Complete Example

---
name: pdf-tools
version: 2.1.0
description: Extract text, tables, and images from PDF documents
author: askskills
license: MIT
keywords:
  - pdf
  - document
  - extract
  - text
  - tables

contract:
  inputs:
    - name: file_path
      type: file
      required: true
      description: Path to the PDF file
    - name: operation
      type: string
      required: true
      enum: [extract_text, extract_tables, extract_images]
    - name: pages
      type: string
      description: Page range (e.g., "1-5" or "1,3,5")
  outputs:
    - name: result
      type: object
      description: Extracted content based on operation

capabilities:
  - capability: file:read
    reason: To read PDF files from disk
    constraints:
      paths: ["*.pdf"]

tests:
  - name: extract-text-basic
    input:
      file_path: "test.pdf"
      operation: "extract_text"
    expect:
      success: true

---

# PDF Tools

Extract text, tables, and images from PDF documents with high accuracy.

## Operations

### Extract Text
Extract all text content while preserving layout and formatting.

### Extract Tables
Parse tables into structured JSON data with headers and rows.

### Extract Images
Extract embedded images and save to specified location.

## Usage Examples

"Extract all text from invoice.pdf"
"Get the tables from pages 2-5 of financial_report.pdf"
"Extract images from presentation.pdf"

## Notes

- Supports PDF versions 1.0 through 2.0
- OCR not included; works with text-based PDFs only
- Large files may take longer to process