SKILLs Matter: Everyone Can Coach an AI Agent
Nine people. Two days. One AI agent to teach. The best teachers turned out to be the ones who had never written a line of code.
We sat down in one room. Nine people. Four engineers on one side, three domain experts and a lawyer on the other, and me in the middle — a Principal Engineer moderating a two-day workshop whose goal was to teach our internal AI agent everything it needed to know about our business domain.
And then it hit me.
“We want to teach the agent — but how exactly are we going to do that?”
I looked around the room. Half of these people had never written a line of code in their lives. They’re here for two full days. The classic approach would be: business explains what to write, engineers write it, deploy it, business waits. We all know how efficient that is.
But what if everyone could work simultaneously? What if the non-technical people could teach the agent directly, right now, without waiting for an engineer to translate their knowledge into code?
The idea came out of nowhere, casually, almost by accident:
“Let’s use Google Drive.”
I said it out loud before I even checked if it was possible. The room lit up — the prospect of building something live, seeing the effect here and now, that’s the kind of energy that fuels a workshop. I had just promised everyone in that room the power to teach an AI agent directly. I didn’t know if it would work.
A quick prompt to my AI coding assistant. I let it run. Meanwhile, I started explaining what SKILLs are, how to write them well, what LLMs respond to and what they don’t.
One eye on the room. One eye on my laptop, watching the agent work.
Thirty minutes later, the first version was deployed. It worked.
From that moment on, the workshop stopped being a lecture. Everyone in the room got their hands dirty — engineers, domain experts, the lawyer. All writing, all testing, all seeing the results of their work reflected in the agent within a minute. Nobody was waiting for anyone else.
“I like having good ideas.”
Quick Navigation:
- What Is a SKILL? — Quick intro for the uninitiated
- The Workshop — Two days, nine people, one agent
- The Setup — Google Docs, live sync, and a 1-minute feedback loop
- What Makes a Good SKILL — Lessons from real failures
- Be a Good Coach — The bigger picture
What Is a SKILL?
A SKILL is a document that teaches an AI agent how to do something specific — or how to understand something specific. Not every SKILL involves a tool. Some are instruction manuals: “here’s how to use this API, step by step.” Others are pure knowledge: “here’s how loan consolidation works, what the edge cases are, and why we handle early repayment this way.”
Think of it like a bookshelf. The agent can see every spine — it knows what books are available. But it only opens the one it needs, when it needs it. That’s the key difference from a static instruction set that’s always active, always loaded, always taking up space. A SKILL sits on the shelf until it’s relevant.
Some of those books are tool manuals — they describe how to operate an API, a CLI, a database. Others are knowledge books — they encode domain expertise, business rules, processes, context. The kind of things that live in someone’s head or buried in a Confluence page nobody reads.
| Type | What it is | Example |
|---|---|---|
| Tool SKILL | Instructions for operating a specific tool + optional executable code | ”Use this SKILL to check delivery status. Call the tracking API with the order ID, parse the response, show ETA.” |
| Knowledge SKILL | Domain context, business rules, processes — no code needed | ”Loan consolidation merges multiple loans into one. Early repayment fees apply only when…” |
Both types live as simple documents. No framework, no SDK. A file that an LLM reads before it starts working. This is not just dumping documents into retrieval — a SKILL is activated intentionally, has a scoped description, and teaches the agent how to behave or reason in a specific context.
The important thing is this: a SKILL doesn’t have to be code. It can be knowledge. And knowledge doesn’t require a developer to write.
The Workshop
Names and specific processes have been changed to protect internal company information. The story faithfully reflects what actually happened in the room.
Day 1: Orientation and First SKILLs
While the integration was being built, I ran a session on what makes a good SKILL — scope, boundaries, common mistakes, the mindset shift. Then the room split naturally. Not by seniority — by knowledge type.
Domain experts and legal started writing SKILLs immediately. They knew the business rules, the edge cases, the things that “everyone knows” but nobody had ever written down. A lawyer writing a SKILL about a process she knew inside out — both as a user and as someone who had examined every legal detail of it — turned out to be more valuable than any API integration we built that day.
Engineers focused on the technical layer — tool integrations, API wrappers, data connectors. The kind of work that requires code. While they were wrestling with infrastructure and integration edge cases, the agent was getting smarter by the hour — powered by the domain experts writing SKILLs on the other side of the room.
I moved between groups, answering questions, reviewing SKILLs, suggesting improvements. Helped Ewa — one of the domain experts — cut her three-page SKILL down to half a page. The agent’s responses sharpened immediately. Showed Kasia — one of the engineers — that two lines of example in her tool SKILL would fix the formatting inconsistencies she’d been fighting all morning. Small adjustments, big impact.
That afternoon, I heard frustration from across the room. Marta — one of the domain experts — had been refining her SKILL for over an hour, and the agent was still getting it wrong. “I’ve rewritten this three times,” she said. “When you ask about operation status, it makes up an answer first and then says the information isn’t available.”
I looked at her SKILL. It was well-written — clear scope, good boundaries. The problem wasn’t in what she wrote. I turned to Michał, one of the engineers. “Does the API expose operation status?” Michał checked. “Yeah — metadata, state field.”
There it was. The information existed. The agent had access to the tool. But the SKILL didn’t tell the agent where to find it. Marta described what the agent should say, but not where to look. A good SKILL doesn’t just describe expected behavior — it points the agent to the right data source and explains how to interpret what it finds.
I stopped the room. This was the piece I’d skipped in the morning session. I explained that the agent can pull data from tools, but it needs to be told which tool to use and how to read the response. And sometimes the data simply isn’t there yet — that’s when the engineering side needs to step in and build it.
Day 2: Iteration and Coaching
By morning, the agent already knew more than it did 24 hours ago. People came in, tested their SKILLs from yesterday, found gaps, and fixed them.
The feedback loop was tight: write → wait 60 seconds → test → fix → repeat. The domain experts didn’t need an engineer to deploy their changes. They didn’t need to wait for an engineer to review and deploy their changes. They wrote in Google Docs, and the agent learned.
But parallel work has its traps. Adam had built a SKILL for accounting operations on day 1 — tested it, everything worked perfectly. Day 2, it broke. Sometimes the agent answered correctly, sometimes it responded with completely unrelated information. Adam looked at me, frustrated. “Marcin, what’s going on?”
I pulled up the agent’s logs. In the failing conversations, the agent wasn’t loading Adam’s SKILL at all — it was pulling contract_operations, a SKILL that Ewa had created that morning. Remember the bookshelf? The agent reads the spines to decide which book to open. Adam’s spine said “use this for knowledge about accounting operations.” Ewa’s said “use this for knowledge about contract operations.” A user asking about “operation status” saw two nearly identical spines — and the agent grabbed one at random.
The fix: make every description specific enough that there’s never a contest. Not “use this for operations” — but “use this when the user asks about booking entries, ledger reconciliation, or payment posting.”
Problems like these kept coming up — a dozen more over the two days. Missing data, misinterpreted fields, an agent confidently presenting nonsense. For the first few, I played the middleman: domain expert flags a problem, I diagnose it, I route it to the right engineer. But by midday on day 2, I was no longer needed. The teams self-organized. Marta walked over to Tomek directly. “The agent doesn’t know about early termination fees — is that in the API?” “Not yet. Give me twenty minutes.”
The collaboration ran both ways. Agent showing raw technical IDs to users? Domain experts added a line to the SKILL: “never display internal identifiers.” Missing data source? Engineers added a tool. Agent guessing instead of admitting ignorance? Another line in the SKILL. Bug in the response? Engineers fixed the API. Each fix took minutes, not sprints.
By the end of day 2, we had a library of SKILLs covering core domain concepts, regulatory constraints, data interpretation rules, and tool usage patterns. Written by nine people, most of whom had never touched a SKILL before.
When our director stopped by that afternoon, I got to say something I hadn’t expected to say when the workshop started:
“The best programmers in this room over the past two days were the people who have never written a line of code.”
The Setup
The mechanism I built in those 30 minutes was simple:
SKILLs in Google Docs. Each SKILL lives in its own folder on a shared Drive — a Google Doc named SKILL.md with a short header describing what the SKILL is about, following the Agent Skills standard. Optionally, a references/ subfolder next to it with additional documents the agent can pull in when it needs more context. The only difference from a developer’s workflow? You’re writing in Google Docs instead of a code editor. Headings, bullet points, plain language. No markdown syntax to learn, no git to wrestle, no terminal to open.
Live sync. A background worker polls Google Drive every 60 seconds, pulls any new or modified docs with their metadata, and caches them in the application. Edit a doc, wait a minute, test the agent. That’s the feedback loop.
That was it. No fancy infrastructure. A Google Drive folder and a sync script. During the workshop, I monitored errors directly in the agent’s logs — if someone’s SKILL failed to load, I caught it in real-time and helped them fix it.
After the workshop, I built a status dashboard — a simple page showing all loaded SKILLs, last update time, and any errors. The goal was to give the non-technical team a feedback loop they could use on their own, without me watching the logs. The workshop was two days, but the agent’s education didn’t stop when we left the room.
Worth being clear about this: it was a quick experiment, not a production-ready architecture. We weren’t building a platform to deploy company-wide. We were testing whether non-technical people could teach an agent directly — without a developer in the middle, without a sprint of translation. That was the whole bet. And it worked. Being non-technical stopped being a blocker. Everyone in that room had a direct, immediate impact on the product we were shaping together. Of course, this doesn’t mean skipping review, ownership, or quality gates — it means moving the first iteration closer to the people who actually understand the domain.
What Makes a Good SKILL
The workshop was a crash course in SKILL writing — and the lessons came from real failures, not theory. Here’s what we learned the hard way:
Keep it short. Ewa’s three-page SKILL was the first lesson. Every word lands in the agent’s working memory and competes for attention. If you need extra detail, put it in a separate reference file — the agent pulls it in only when relevant.
Skip what the agent already knows. Don’t explain what a loan is — the LLM knows that. Focus on what makes your loans different: the edge cases, the internal rules, the things that aren’t on Wikipedia.
Be unambiguous. Adam and Ewa’s collision showed what happens when two SKILLs have overlapping descriptions — the agent guesses. If the rule is “always reject requests older than 90 days,” say that — don’t say “consider rejecting.”
Tell the agent where to look, not just what to say. Marta’s SKILL described the expected behavior perfectly but didn’t point to the data source. A good SKILL connects knowledge to tools.
Add examples. Kasia’s formatting problem disappeared with two lines of example. One good example beats a paragraph of explanation.
Iterate. Nobody wrote a perfect SKILL on the first try. The 60-second feedback loop meant that “close enough” was the starting point, not the goal.
For a deeper dive into SKILL writing patterns, see the best practices guide on agentskills.io.
Be a Good Coach
Writing good SKILLs is one thing. But the workshop taught us something bigger about how to build agents as a team:
Cross the aisle. The best fixes happened when domain experts and engineers talked directly. Not through a moderator, not through a ticket — face to face, in the same room. It wasn’t “tech builds, business reviews.” It was one team, one agent, everyone contributing what they knew best. That’s not how most AI projects work. But maybe it should be.
The agent doesn’t care about your job title. The lawyer’s SKILL was the most impactful document produced during the entire workshop — not because she knew AI, but because she knew the process from every angle: as a user, as a legal expert, in every detail. Legal thinking is SKILL thinking: precise language, defined boundaries, explicit exceptions. The domain experts wrote SKILLs that engineers couldn’t have written — not because the engineers lacked skill, but because they lacked the years of living inside the process — the unwritten rules, the edge cases that never made it into any documentation.
What we did in that room doesn’t have to stay in a workshop. SKILLs are the interface between two worlds: engineers write tool SKILLs — the plumbing. Domain experts write knowledge SKILLs — the business rules. Nobody has to become the other side. This can be everyday work.
Nine people walked into that room. Half of them had never written a line of code. Two days later, the agent knew the business better than any of us individually — because all of us had taught it.
But what happens when an agent has a dozen SKILLs and they start working together? That’s the next chapter.
Be a good coach. SKILLs matter.
Related posts:
- Too Lazy to Click: AI Shopping — Where the Delio SKILL was born
- A Day in the Life of a Principal Engineer — SKILLs at work, five workstreams at once