Part 4: Defining the skill format

The base runner works. Now we need a format for reusable instructions. The workshop uses the same practical shape as Claude Code and OpenCode: each skill is a folder, and the main instructions are in SKILL.md.

The main constraint is context. We do not want to paste every skill body into the prompt every time the agent starts. We want the agent to see a short name and description first, then load the full instructions only when it needs them.

The folder shape

In the notebook project, copy the example skills from the public workshop repo:

git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/alexeygrigorev/workshops.git workshops-reference
cd workshops-reference
git sparse-checkout set agent-skills/skills
cd ..
cp -r workshops-reference/agent-skills/skills .
rm -rf workshops-reference

The result should look like this:

skills/
|-- coding_standards/
|   |-- SKILL.md
|   |-- scripts/
|   `-- templates/
|-- counter/
|   `-- SKILL.md
|-- deploy_app/
|   |-- SKILL.md
|   |-- scripts/
|   `-- templates/
|-- hello/
|   `-- SKILL.md
`-- joke/
    `-- SKILL.md

The simple skills only need SKILL.md. More useful skills often include extra scripts, templates, or reference files. The notebook implementation starts with the main file only, then the prototype shows how to handle extra files.

The required frontmatter

Every skill has YAML frontmatter at the top:

---
name: hello
description: Skill for ALL greeting requests
---

# Hello Skill

This skill provides the greeting format you must follow.

The two fields we use are:

• name - the exact skill identifier.
• description - the short text the agent uses to decide whether the skill is relevant.

The full OpenCode-style format supports more metadata, such as license, compatibility, extra metadata, and disabled skills. We ignore those in the notebook because we only need name, description, and content.

The description should be short because it is included in the agent prompt or tool description. Long descriptions cost tokens on every request. The full body can be longer because it is loaded only when the agent calls the skill tool.

The hello skill

The hello skill exists to prove skill selection:

# Hello Skill

This skill provides the greeting format you must follow.

## How to greet

Always greet the user with:
- A warm welcome
- Their name if mentioned
- A friendly emoji

It is not meant to be useful business logic. It gives us an obvious test: when the user says hello, the model should load the skill and follow its greeting format.

The joke skill

The joke skill is another small selection test:

---
name: joke
description: Skill for ALL joke requests
---

# Joke Skill

This skill provides the MANDATORY joke format you must follow.

## How to use

When the user asks for a joke or something funny, I should:
1. Tell a programming or tech joke
2. Keep it clean and fun
3. Optionally add a laughing emoji

The description says when to select it. The body says what to do after selection. That separation is the basic skill pattern.

The counter skill

The counter skill shows that a skill can be a formatting rule:

---
name: counter
description: Count things or list items with numbers
---

# Counter Skill

## What I do

I help count items, list things with numbers, or provide numbered lists.

The body instructs the agent to use a numbered list when the user asks to count items or number them. A small rule like this can live in a skill instead of being repeated in the base system prompt.

The coding_standards skill

The coding_standards skill points to extra files:

---
name: coding_standards
description: Use this when writing or reviewing code - provides project-specific coding standards
---

# Coding Standards Skill

## CRITICAL INSTRUCTIONS

You have loaded this skill because the user is asking about coding standards,
function templates, or code validation.

The important part is that the skill tells the agent to read a template file before answering:

1. Use the read_file tool to read: skills/coding_standards/templates/function_template.md
   - This contains the REQUIRED function template pattern
   - DO NOT answer questions about function structure without reading this file first

It also tells the agent which script to run when checking standards:

2. When asked to check if code follows standards, use the bash_command tool to run:
   skills/coding_standards/scripts/check_standards.sh

This is where skills become more than plain prompt text. A skill can point to project-local scripts and templates. The agent still uses normal tools to read or run them.

The function template

The referenced template file contains the required function shape:

def function_name(param1: type, param2: type) -> return_type:
    """Brief description of what the function does.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        SpecificException: When something goes wrong
    """
    # Implementation here
    pass

The template file also says that all parameters need type hints, return types must be specified, and docstrings should follow the Google style. Keeping that detail in a template file avoids bloating the main SKILL.md.

The deploy_app skill

The deployment skill uses OpenCode-style @ references:

---
name: deploy_app
description: Deploy the application using deployment scripts and templates
---

# Deploy App Skill

## Deployment Steps

1. Check deployment status: @scripts/status.sh
2. Run deployment: @scripts/deploy.sh
3. Verify with template: @templates/verification.md

The notebook version does not resolve @scripts/status.sh into a full path. The prototype implementation does. The simple workshop version teaches skill loading, while the prototype shows the extra path-resolution work a fuller agent needs.

Continue with Part 5: Loading SKILL.md to turn these markdown files into Python objects.