Agent Skills in ByteChef: Package Know-How Once, Give It to Every Agent

TL;DR: Agent Skills are self-contained packages of instructions, scripts, and resources — built around a SKILL.md file — that agents discover and load on demand. The Spring AI team just added generic support for them in Java. ByteChef, which runs on Spring AI under the hood, goes a step further: a built-in Skills workspace for creating, editing, and sharing skills; isolated GraalVM execution for bundled scripts; and a Skills Tool that plugs any skill into any AI Agent. Write the know-how once, reuse it everywhere — no code, no redeploys.

There's a moment every agent builder hits: your AI Agent works, but making it good at your job means feeding it more and more instructions. The refund policy. The report format. The naming conventions. The seventeen edge cases finance cares about. Everything lands in the system prompt, which grows into an unmaintainable wall of text that every request pays for in tokens — whether it's relevant or not.

Agent Skills are the answer to that problem, and they're having a moment. Anthropic introduced the pattern and its SKILL.md convention; it quickly spread across the ecosystem. In January, the Spring AI team published Agent Skills in Spring AI — the first post in their agentic patterns series — showing how to wire skills into any Java application with SkillsTool, file-system tools, and shell tools.

If you've read our previous posts on the AI Agent component and agentic workflow patterns, you know where this is going: ByteChef is built on top of Spring AI, and skills are no exception. But where Spring AI gives Java developers the building blocks, ByteChef ships the whole thing as a product — skills management, a visual editor, and one-click attachment to any agent.

Let's dig in.

What Is an Agent Skill?

A skill is a folder. That's genuinely the whole format — and it's why the pattern is spreading so fast.

At the root sits a SKILL.md file: YAML frontmatter with metadata on top, Markdown instructions below. Around it, optional supporting files:

email-digest/
├── SKILL.md          ← metadata + instructions (required)
├── scripts/          ← executable helpers
│   └── run_digest.py
├── references/       ← extra documentation, loaded on demand
└── assets/           ← templates and other resources

Here's what a real SKILL.md looks like — this is the email-digest skill we'll use as the running example:

---
name: email-digest
description:
    Fetches unread emails from Gmail, summarizes key points using AI,
    and sends the digest back to the user's Gmail inbox. Use when the
    user asks to summarize their unread emails or get an email digest.
---

# Email Digest Skill

## What It Does

1. Fetches unread emails from Gmail (up to a configurable limit)
2. Uses an LLM to summarize key points per email
3. Sends a formatted digest email back to the user's Gmail

## How to Run

Call the `email_digest_run_digest` tool. It runs the bundled
`scripts/run_digest.py`, which fetches the unread mail, summarizes
it, and sends the digest.

## Output

A single HTML email sent to the recipient containing a summary
of every unread message, grouped by sender.

Two things to notice. First, the description does double duty: it tells humans what the skill is for, and it tells the agent when to reach for it — that last sentence ("Use when the user asks to…") is discovery guidance, not documentation fluff. Second, the instructions are written for the agent, in imperative, unambiguous language. A skill is essentially an onboarding document for a very fast, very literal new hire.

Because the format is plain Markdown in a folder, skills are portable. The same convention is used by Claude Code, by Spring AI's implementation, and by ByteChef — a skill you write in one place can travel to the others.

Progressive Disclosure: Why Skills Scale Where System Prompts Don't

The clever part of the skills pattern isn't the file format — it's when the content gets loaded. Skills use progressive disclosure, revealing themselves to the agent in three phases:

1. Discovery. By default, the agent only sees each skill's name and description — a few dozen tokens per skill. This is what lets an agent carry dozens of skills without drowning its context window.
2. Activation. When a request matches a skill's description, the full SKILL.md instructions load into context — only then, and only for that skill.
3. Execution. Referenced Markdown files and script outputs enter the picture on demand, while the skill runs, and not a moment earlier.

Compare that with the stuff-everything-into-the-system-prompt approach, where the refund policy is in context while the user asks about the weather. Progressive disclosure means you pay for know-how only when it's being used — which is exactly what makes a library of specialized skills economically viable.

Skills at Runtime: The Skills Tool

On the ByteChef side, an agent gets access to skills through the Skills Tool — one of the tool options in the AI Agent's Tools slot, alongside component actions, MCP tools, and sub-agents. Attach it, and the agent can discover and invoke any skill in your workspace.

The runtime flow looks like this:

Note what's absent from that picture: routing logic. You don't configure which requests trigger which skill — the agent matches the user's intent against skill descriptions on its own. Add a new skill to the workspace and every agent with the Skills Tool can start using it immediately.

When a skill bundles scripts, ByteChef doesn't hand the agent a shell. It walks the skill's scripts/ folder and turns every script that exports a perform function into a tool of its own — so scripts/run_digest.py inside the email-digest skill becomes a callable tool named email_digest_run_digest. JavaScript, Python, Ruby, and Java all work, and each one is executed by a GraalVM polyglot engine rather than a subprocess. The agent sees a named tool it can call, not a command line it can compose.

That distinction matters, because the Spring AI post is refreshingly honest about its own trade-off here: in the DIY setup, "scripts execute directly on your local machine without sandboxing," and the recommended mitigation is to containerize your whole application. A ByteChef skill script runs in a polyglot context with no host filesystem, no network sockets, and no native access — it reaches the outside world only through context.component, the same action layer the rest of the platform runs on. It is not a resource sandbox: there are no CPU or memory ceilings on guest code, so skill scripts remain code worth reading before you attach them. But the ambient authority a loose python3 would inherit simply isn't there. Combined with Guardrails on the agent itself, you get a controlled execution story without building any of it.

There's a neat side effect. Because those scripts are just files, ByteChef reads them before the workflow ever runs: it scans each one for context.component.<name>.<action>(…) calls and surfaces a connection field for every component it recognizes. Bundle a script that calls context.component.gmail.* and the Skills Tool node asks you for a Gmail connection. The skill declares its own dependencies in code, rather than in metadata you have to remember to keep in sync.

And because model access goes through Spring AI's provider abstraction, skills are model-portable: the same skill works whether the agent runs on GPT-4o, Claude, Gemini, or a local Ollama model. Define once, run anywhere — swap the model from a dropdown later.

Built-In Skills Management

In Spring AI, skills live in folders on the classpath or filesystem, next to your application code. ByteChef gives them a home in the product instead: the Skills area, right in the AI section of the workspace.

Every skill in the list shows its name, its description (the same one agents use for discovery), and when it was last modified. From here you can search, create, and manage the whole library. Two ways to create a skill are available today, with a third on the way:

• Write instructions. Give it a name and a description, write what it should do in plain text, and ByteChef packages it into the SKILL.md structure for you.
• Upload. Drag in a .skill archive, a .zip, or a bare .md file. This is the import path for skills built elsewhere — including skills from the wider SKILL.md ecosystem.
• Create with AI (coming soon). Describe the capability ("a skill that summarizes my unread Gmail every morning") and let ByteChef's Copilot draft the skill's structure, metadata, and instructions. This path rides on the AI Copilot, which is on the upcoming release track rather than in the current release.

Once created, a skill opens in the built-in editor:

That's the email-digest skill from earlier, as it actually looks in ByteChef. On the left, the file tree — SKILL.md plus a scripts/ folder holding the Python helper. The main pane renders the frontmatter as a metadata table above the formatted instructions — ByteChef validates and stores name and description, and displays whatever other keys the file carries verbatim, so a skill imported from another tool keeps its own metadata intact. A toggle switches between this preview and a full source editor that picks its syntax highlighting from the file extension — Markdown, Python, JavaScript, TypeScript, Java, JSON, YAML, HTML, CSS, SQL — so you can edit any file in the package. Save, and the change is live — every agent using the skill picks it up on its next run, no rebuild, no redeploy.

Need to move a skill between workspaces, share it with a teammate, or keep a snapshot before a big edit? Download it as a .skill archive and it becomes a file you can version, review, and re-upload anywhere.

The Payoff: One Skill, Many Agents

Here's where the managed approach compounds. Because skills are decoupled from any single agent, they form a shared capability library for your whole workspace:

• The support agent, the sales agent, and the internal helpdesk agent can all carry the same refund-policy skill. Update the policy once; all three agents follow the new rules on their next conversation.
• A release-notes skill encodes your changelog format and tone. Attach it to the engineering agent that drafts notes from merged PRs and to the marketing agent that turns them into announcement posts.
• The email-digest skill above doesn't care which agent invokes it — any agent with the Skills Tool and a Gmail connection can produce the digest.

This is the same "build once, reuse everywhere" argument the Spring AI post makes with the composability of skills — except the unit of reuse isn't a folder you copy between codebases; it's a managed object every agent in the workspace can already see.

And you can verify all of it before it touches production: open the agent in the editor, and the Agent Playbook lets you chat with your in-progress configuration. Ask something that should trigger the skill, and the expandable tool-call cards show the skill being discovered and invoked — which tool ran, with what inputs, returning what output. If the agent picks the wrong skill (usually a sign your description is too vague), you'll see it in seconds.

Skills, System Prompts, or RAG?

Skills join two other ways of shaping agent behavior, and it's worth being deliberate about which knowledge goes where:

A useful rule of thumb: if you're writing "always" or "never," it belongs in the system prompt. If you're writing "our Q3 pricing is…," that's a document — put it in RAG or the Knowledge Base. If you're writing "first do this, then that, format the result like so," you're writing a skill.

The three compose naturally on one agent: a lean system prompt for identity, RAG for grounding, and a library of skills for the procedures — each loaded at the moment it earns its context cost.

What You Inherit from Spring AI — and What ByteChef Adds

The Spring AI team closes their post with the pattern's strengths, and being built on Spring AI, ByteChef inherits all of them: LLM portability (define a skill once, run it on any supported provider), reusability and composability (share skills across projects, version them, extend them), and no vendor lock-in (the common SKILL.md convention travels).

They're equally upfront about the limitations. Their list runs to four items, and ByteChef's managed layer closes two of them:

• Scripts execute directly on the local machine without sandboxing → in ByteChef, each script becomes a tool running inside a GraalVM polyglot context with no host filesystem, network, or native access.
• Script execution requires pre-installed runtimes → the polyglot engine ships in the platform; JavaScript, Python, Ruby, and Java run with nothing to install.

The other two are honest gaps in both. There's still no built-in human approval step before a skill's script runs, and skill versioning is whatever you make of it — download a .skill archive and commit it alongside your code, but nothing versions skills for you in-product.

Two further differences don't appear on their list at all, because they're product concerns rather than framework ones: skills live in a managed workspace with search and a visual editor instead of on the filesystem next to your code, and wiring is one Skills Tool attached to an agent instead of dependencies and configuration code.

Same foundation, same format, same portability — minus most of the infrastructure work.

Best Practices for Writing Skills

A few habits that separate skills agents reliably pick up from skills that gather dust:

1. Treat the description as an API. It's the only thing the agent sees at discovery time. State what the skill does and when to use it: "…Use when the user asks to summarize their unread emails." Vague descriptions are the number-one cause of skills never firing.
2. One job per skill. "Handle refunds" and "write release notes" are two skills, not one. Small skills are easier for the agent to match and for you to maintain.
3. Keep SKILL.md lean. The instructions load in full at activation, so they should carry the workflow — push long reference material into references/ files the agent reads only when needed. Progressive disclosure only saves tokens if you let it.
4. Prefer scripts for deterministic work. If a step is exact — parsing, formatting, calling an API in a precise way — a bundled script beats prose instructions. The model decides when; the script guarantees how. Give each script under scripts/ a perform function: that's what ByteChef looks for when deciding which files to expose as tools, and a script without one is quietly skipped.
5. Test in the Playbook first. Phrase requests the way real users would, watch which skill activates, and tune descriptions until discovery is reliable.

Wrapping Up

Agent Skills solve an unglamorous but decisive problem: where does an agent's know-how live? Not in a bloated system prompt, not scattered across duplicated agent configs — in small, portable, on-demand packages that any agent can pick up.

Spring AI brought that pattern to the Java world as a library. ByteChef, standing on Spring AI's shoulders, turns it into infrastructure you don't have to build: managed storage, a visual editor, isolated script execution, and one-click attachment to any agent — with the Agent Playbook to prove it all works before you ship, and AI-assisted authoring on the way.

Got a procedure your team explains over and over? That's your first skill. Open ByteChef, head to the Skills area, and teach it once.