SuperAPI AI Directory

write-a-skill

General & other

View repository

Updated 10-16 10:22

About this skill

Writing Skills

Process

  1. Gather requirements — Ask the user:

    • What task/domain does the skill cover?
    • Which specific use cases should it handle?
    • Does it need executable scripts, or only instructions?
    • Are there reference materials to include?
  2. Draft the skill — Create:

    • SKILL.md with concise instructions
    • If content exceeds 500 lines, create additional reference files
    • If deterministic operations are needed, create utility scripts
  3. Review with user — Show the draft and ask:

    • Does it cover your use cases?
    • Is anything missing or unclear?
    • Is there any section that should be more detailed or shorter?

Skill Structure

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md Template

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]

Description Requirements

The description is what the agent seesthe only thing it seeswhen deciding whether to load the skill. It appears in the system prompt alongside other installed skills. The agent reads these descriptions and selects the relevant skill based on the user's request.

Goal: Give the agent enough information to know:

  1. What capability this skill provides
  2. When/why to trigger it (specific keywords, contexts, file types)

Format:

  • Maximum 1024 chars
  • Use third person
  • The first sentence states what it does
  • Second sentence: "Use when [specific triggers]"

Good example:

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

Bad example:

Helps with documents.

A bad example fails to let the agent distinguish it from other document skills.

When to Add Scripts

Add utility scripts when:

  • The operation is deterministic (validation, formatting)
  • The same piece of code would be regenerated repeatedly
  • Errors require explicit handling

Compared to generated code, scripts save tokens and improve reliability.

When to Split Files

Split into separate files when:

  • SKILL.md exceeds 100 lines
  • The content has different domains (finance vs sales schemas)
  • Advanced features are rarely needed

Review Checklist

After the draft is complete, verify:

  • The description contains triggers ("Use when...")
  • SKILL.md is under 100 lines
  • There is no time-sensitive info
  • Terminology is consistent
  • Contains concrete examples
  • References go only one level deep