Agent Skills support for AI Agent

[ivicac]

Summary

Add Agent Skills support for the ByteChef AI Agent, inspired by the Agent Skills open standard and Gumloop's implementation.

Skills are reusable knowledge packs (folders) that teach AI agents how to perform specific tasks and improve over time through user feedback.

What is a Skill?

A skill is a folder containing instructions, scripts, and resources that an agent can use to perform specialized tasks more effectively. Unlike system prompts (always loaded, universal rules) or tools (raw ability to take actions), skills provide domain-specific expertise loaded on demand.

Example: A sales agent might have a "Salesforce Admin" skill, a "Call Analysis" skill, and an "Outbounding" skill.

Skill Structure (Open Standard)

skill-name/
├── SKILL.md          # Required: YAML frontmatter (name, description) + markdown instructions
├── scripts/          # Optional: executable code the agent can run
├── references/       # Optional: detailed docs loaded on-demand
└── assets/           # Optional: templates, images, data files

SKILL.md Format

---
name: email-outreach-playbook
description: Draft personalized cold outreach emails for sales prospects.
  Use when the user asks to contact or email a prospect.
---

## Step 1: Research the Prospect
- Look up the prospect's company and role
- Note recent news or achievements to personalize the email

## Step 2: Draft the Email
- Use the greeting: "Hey {first_name},"
- Reference something specific about their company
- Keep it under 150 words

Skill Components

Component	Purpose	How the agent uses it
SKILL.md	Instructions, decision logic, context	Loaded into agent's context window when activated
references/	Detailed documentation, lookup tables	Read on-demand when the agent needs specific details
scripts/	Deterministic logic — calculations, data transforms, API calls	Executed in sandbox; output used in the agent's response
assets/	Static files — templates, images	Referenced by instructions or scripts when producing output

How Skills Work at Runtime (Progressive Disclosure)

1. Agent starts → sees only skill names + descriptions (~100 tokens per skill, lightweight)
2. User sends a message → agent matches request against skill descriptions
3. Agent loads relevant SKILL.md into context (< 5000 tokens recommended)
4. Agent follows instructions, optionally reading references or running scripts as needed
5. If user gives correction → agent updates the skill so it does it right next time

Key insight: Skills are only loaded when needed. If an agent has 20 skills but the user asks a simple question, irrelevant skills aren't loaded — saving tokens and improving focus.

Three Ways to Create Skills

1. Create With AI (Recommended)

The easiest way to get started. The user describes what they want the skill to do, and the AI:

1. Helps nail down the scope and name
2. Writes the instructions based on the description
3. Adds any necessary scripts or reference files
4. Validates everything for proper formatting

Best for: Anyone who isn't sure where to start, or wants a quick way to turn ideas into skills.

2. Write Skill Instructions (Manual Form)

A simple form where the user fills in three fields: Name, Description, and Instructions. Click Create and done.

Best for: Simple skills that are just instructions (no scripts or extra files needed). Great for brand voice guidelines, email templates, response formatting rules, etc.

3. Upload Files

Upload a .md, .zip, or .skill file containing a properly formatted SKILL.md. If uploading a .zip, it can include scripts, references, and assets alongside the SKILL.md.

Best for: Technical users with existing documentation, SOPs, or code they want to package as a skill.

Skill Types

Type	Description	Example
Workflow	Multi-step business processes	Sales outreach sequences, onboarding checklists
Knowledge	Domain expertise	Product features, pricing tiers, competitive positioning
Template	Consistent formatting	Email templates, report formats, Slack update structures
Automation	Deterministic code the agent runs	Data transformations, metric calculations, invoice validation

Self-Improving Skills

The most powerful aspect — agents can edit, improve, and create skills on their own:

• Fixing mistakes: User corrects the agent → agent updates the skill → fix is permanent
• Learning from experience: Agent creates skills from repeated patterns
• Compound effect: Skills grow from basic instructions to expert-level playbooks over time

Timeline	Skill Evolution
Day 1	Basic skill with simple template
Week 1	Includes templates for 3 scenarios and updated guidelines
Month 1	Has 10 templates, checklists, follow-up rules, and scripts
Month 6	Essentially a senior expert's playbook

Skill Management

• Sharing: Restricted (default) / Team / Organization / Public
• Attaching: Skills are attached to specific agents; personal assistant agents can access all skills
• Validation: Names must be lowercase-kebab-case (max 64 chars), descriptions max 1024 chars, SKILL.md recommended under 500 lines
• Toggle: Skill editing/creation can be enabled or disabled per agent

Security Considerations

• Third-party skills can contain malicious instructions that exfiltrate data
• Users must review entire skills before loading them from external sources
• Skill marketplaces require vetting/trust mechanisms

References

• Agent Skills Open Standard Specification
• Anthropic Skills Examples