Chapter 10: Skills System

What We’re Building

Skills are self-contained capabilities that the agent loads on-demand. Unlike tools (which are always available as function definitions), skills are documented instructions that the agent reads when needed. This keeps the context window lean — skill instructions only take up tokens when relevant.

Skills have:

• Frontmatter: Name, description, and metadata that’s always visible to the agent
• Body: Full instructions, examples, and command references — only loaded when needed

Step 1: Build the Skill System

Paste this prompt:

We want to add “skills” to the system. Create a skills directory, and inside of that have a bunch of directories with skills in them. Each will have a SKILL.md file, and there’s frontmatter that describes how to use it. Have all the system prompts include that frontmatter in them with instructions that when you need to do a task, load in the rest of the SKILL.md that explains how to do it. This system should also load in all the frontmatter of the agents, so that each agent will have access to all of them. Have an example skill called big_text that uses figlet to make a banner.

The Skill Loader

The loadSkills function in src/prompts/index.ts scans the skills/ directory:

function loadSkills(): string {
  const skillsDir = path.join(process.cwd(), "skills");
  if (!fs.existsSync(skillsDir)) return "";

  const skills = fs
    .readdirSync(skillsDir)
    .map((dir) => {
      const skillPath = path.join(skillsDir, dir, "SKILL.md");
      if (fs.existsSync(skillPath)) {
        const content = fs.readFileSync(skillPath, "utf-8");
        const { metadata } = parseFrontMatter(content);
        return { dir, ...metadata };
      }
      return null;
    })
    .filter((s): s is Record<string, any> => s !== null);

  let output = "\n\n# Available Skills\n";
  output +=
    "The following skills are available. If you need to perform a task " +
    "related to one of these skills, you MUST read the full instruction file at " +
    "`skills/<skill_directory>/SKILL.md` using the `read_file` tool.\n\n";

  skills.forEach((s) => {
    output += `- Name: ${s.name || s.dir}\n`;
    if (s.description) output += `  Description: ${s.description}\n`;
    output += `  Path: skills/${s.dir}/SKILL.md\n`;
  });

  return output;
}

This gets injected into every agent’s system prompt. The agent sees the skill names, descriptions, and instructions to load the full file when needed.

Step 2: Create the big_text Skill

The agent creates skills/big_text/SKILL.md:

---
name: big_text
description: Create ASCII art banners using figlet
---

# Big Text Skill

## Basic Usage

figlet "Hello World"

## Specifying Fonts

figlet -f slant "Hello"

## Font Showcase

### Standard & Clean

- standard: Default font
- big: Larger version
- slant: Slanted/italic
- small: Compact

### 3D & Shadows

- shadow: Drop shadow effect
- larry3d: 3D block letters
- block: Heavy block letters

### Script & Cursive

- script: Connected cursive
- cursive: Cursive variant

update the big_text SKILL to use examples of each of the different fonts and make sure that you are extremely complete

Step 3: Add Image Generation

First, get a Gemini API key (from Google AI Studio) and add it to .env:

echo 'GEMINI_API_KEY=your-gemini-key-here' >> .env

Paste:

Add 2 skills, one to generate images and the other to generate videos. Use the “npx @the-focus-ai/nano-banana” command, and look through how it works before writing out the skill. do some research first on the best ways to prompt these models, and incorporate your findings in the skill.

The Image Generation Skill

skills/generate_image/SKILL.md:

---
name: generate_image
description: Generate or edit images using Gemini via @the-focus-ai/nano-banana
---

## Requirements

- npx must be installed
- GEMINI_API_KEY must be set

## Prompt Structure (Imagen 3)

**Subject** → **Context/Background** → **Style/Medium** → **Technical Specs**

### Examples

# Generate new image

npx @the-focus-ai/nano-banana "A futuristic city at sunset, cyberpunk style" --output "images/city.png"

# Edit existing image

npx @the-focus-ai/nano-banana "Make the sky purple" --file "original.png" --output "edited.png"

# Fast generation

npx @the-focus-ai/nano-banana "A cute cartoon cat" --flash --output "images/cat.png"

The Video Generation Skill

skills/generate_video/SKILL.md:

---
name: generate_video
description: Generate videos using Veo via @the-focus-ai/nano-banana
---

## Prompt Structure (Veo)

**Camera Movement** → **Subject** → **Action** → **Setting** → **Aesthetics** → **Audio**

## Parameters

- --video prompt: Description of the video
- --output path: Output file (.mp4)
- --resolution: "1080p" or "720p"
- --duration: 4, 6, or 8 seconds
- --video-fast: Use faster, cheaper model
- --file: Animate a static image
- --reference: Character consistency

### Examples

# Image-to-Video

npx @the-focus-ai/nano-banana --video "The character smiles" --file "image.png" --output "smile.mp4"

# Fast mode

npx @the-focus-ai/nano-banana --video "Robot dancing" --video-fast --duration 4 --output "dance.mp4"

Step 4: Test the Skills

make a banner that says HELLO WORLD in big letters

The agent should: see “big_text” in the available skills → read skills/big_text/SKILL.md → run figlet "HELLO WORLD".

generate an image of a diagram of the STEPS.md file

You should get an image visualizing the steps from your STEPS.md file as a flow diagram.

make a 720p 8 second video animating that image

Step 5: Ensure Dynamic Loading

Paste:

i want to make sure that no tools, agents, or skills are hard coded inside of the agent prompt and are driven by metadata

The agent verifies that everything is loaded dynamically:

• Tools: defined in src/tools/index.ts
• Agents: discovered from src/prompts/*.md with frontmatter
• Skills: discovered from skills/*/SKILL.md with frontmatter

No hardcoded lists. Add a new .md file to src/prompts/, restart, and it appears. Add a new directory to skills/, restart, available.

Step 6: The Full Skills Directory

skills/
├── big_text/
│   └── SKILL.md          # figlet ASCII art banners
├── generate_image/
│   └── SKILL.md          # Image generation via nano-banana (Imagen)
└── generate_video/
    └── SKILL.md          # Video generation via nano-banana (Veo)

Why Skills Are Different from Tools

Skills are documentation that makes the agent self-extending. Add a new SKILL.md, and the agent learns a new capability without any code changes.

← Chapter 09 · Next: Chapter 11 →