Skills for AI Agents (for memsa memsa) (Lucas B. Nicolosi Soares)（Z-Library）

Page 1

(This page has no text content)

Page 2

Skills for AI Agents Building Context with Dynamic Skills for Agentic Systems With Early Release ebooks, you get books in their earliest form—the author’s raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles. Lucas Soares

Page 3

Skills for AI Agents by Lucas Soares Copyright © 2027 LUCAS NICOLOSI, UNIPESSOAL LDA. All rights reserved. Published by O’Reilly Media, Inc., 141 Stony Circle, Suite 195, Santa Rosa, CA 95401. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (https://oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com. Acquisitions Editor: Nicole Butterfield Development Editor: Rita Fernando Production Editor: Ashley Stussy Cover Designer: Susan Brown Cover Illustrator: Monica Kamsvaag Interior Designer: David Futato Interior Illustrator: Kate Dullea April 2027: First Edition Revision History for the Early Release 2026-06-02: First Release See https://oreilly.com/catalog/errata.csp?isbn=9798341673991 for release details.

Page 4

The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Skills for AI Agents, the cover image, and related trade dress are trademarks of O’Reilly Media, Inc. The views expressed in this work are those of the author and do not represent the publisher’s views. While the publisher and the author have used good faith efforts to ensure that the information and instructions contained in this work are accurate, the publisher and the author disclaim all responsibility for errors or omissions, including without limitation responsibility for damages resulting from the use of or reliance on this work. Use of the information and instructions contained in this work is at your own risk. If any code samples or other technology this work contains or describes is subject to open source licenses or the intellectual property rights of others, it is your responsibility to ensure that your use thereof complies with such licenses and/or rights. 979-8-341-67395-3 [LSI]

Page 5

Brief Table of Contents (Not Yet Final) Part 1: Foundations (unavailable) Chapter 1: The Closed Gap (available) Chapter 2: Skills: Designing for the Context Window (available) Chapter 3: Building Skills (unavailable) Chapter 4: Composition and Advanced Patterns (unavailable) Part 2: Applications (unavailable) Chapter 5: General Business Skills (unavailable) Chapter 6: Domain Specific Skills (unavailable) Chapter 7: Skills in the Wild (unavailable) Appendix A: SKILL.md Reference and Schema (unavailable) Appendix B: Skill Templates (Starter, Domain, Workflow, Integration) (unavailable) Appendix C: Troubleshooting Guide (unavailable)

Page 6

Chapter 1. The Closed Gap A NOTE FOR EARLY RELEASE READERS With Early Release ebooks, you get books in their earliest form—the author’s raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles. This will be the 1st chapter of the final book. Please note that the GitHub repo will be made active later on. If you’d like to be actively involved in reviewing and commenting on this draft, please reach out to the editor at rfernando@oreilly.com. The gap between knowing how to do something and getting it done has been the central bottleneck of human productivity for centuries, and it just closed (sort of).1 Let me explain. When I started teaching at O’Reilly, updating one of my live courses looked like this: a producer would email me asking for refreshed materials. I’d pull up my notes from the last run of the course. I’d open the post-course feedback sheet — students flagging what worked, what didn’t, what to fix. I’d turn all of that into a task list: update these notebooks, re-render those slides, swap out this asset, rewrite that exercise. Then I’d spend the next week actually doing it — editing files, testing code, re-rendering slides, testing again. Four or five hours a day, five days in a row. Call it twenty- five hours of work. Today, the same job takes between twenty and forty minutes. The email still arrives. I still open the notes and the feedback sheet. But now I point Claude Code (AI agent tool that runs inside my computer) at them, type one sentence asking it to update the course, and go do something

Page 7

else. Grab a cup of coffee. Check my emails. When I come back, the refreshed course artifacts are waiting for me to review. What changed? My student ratings haven’t dropped (my average rate has been above 9.5 out of 10 for 3 years), so the quality of my work hasn’t changed. What changed isn’t that AI got smart enough to teach my course for me. What changed is that the update work stopped being mine to do. What changed is that I wrote down how I prepare and teach my courses — in much more detail than the paragraphs above, but not fundamentally different in kind — and I saved it in a file. The file name? SKILL.md The agent reads it and does what it says. That’s it. That’s the whole trick. This chapter is about why that trick wouldn’t have worked ten years ago, or five, or even two — and why a folder with a markdown file (type of text file) in it has become, almost accidentally, the most consequential new format for human expertise in a generation. To understand that, we need to look at two histories that spent the last half- century running on parallel tracks: the long human project of writing down what we know, and the long engineering project of teaching machines to read. The Oldest Problem: Expertise Doesn’t Transfer For most of recorded history, if you wanted someone to do a job the way you did it, you had to stand next to them and show them. A blacksmith’s apprentice learned by watching the smith, then by holding the tongs, then by ruining his first attempts at a horseshoe. A scribe learned by copying. A midwife learned by attending births. The knowledge lived in the body of the person who had it, and the only way to move it was to stand close enough for it to rub off.

Page 8

This was slow. It scaled badly. And it meant that when the expert died, a lot of what they knew died with them. So we invented ways to write expertise down. The apprenticeship became the manual. The manual became the textbook. The textbook became the operating procedure, the field guide, the runbook, the internal wiki, the Notion page, the Confluence space, the README.md at the root of every repository on GitHub. Figure 1-1. Title placeholder Each format was an attempt to do the same thing: take the knowledge out of a person’s head and put it somewhere it could be reused, shared, versioned, and handed to someone new without requiring the original expert to be in the room. None of it worked perfectly as far as this intention goes. The manual always sat a little above or below the real work. Either it was too general to tell you what to do in the specific situation in front of you, or

Page 9

it was so specific that it became obsolete the moment anything changed. The wiki went stale the week after it was written. The runbook assumed you already knew the things it didn’t say. The onboarding doc described the process that used to exist. Every organization on earth has a folder somewhere full of documents that no one reads because no one trusts them, and the institutional knowledge that actually matters still lives in three people’s Slack messages and a senior engineer’s memory. The reason none of these formats ever fully solved the problem is that they all share a quiet assumption, one so deeply baked in that for five thousand years, nobody thought to name it. The reader is human. A manual describes how to do the work. It does not do the work. It waits on a shelf or a server or a shared drive, until a person walks up, reads it, interprets it, fills in the gaps, applies judgment, makes choices the document didn’t anticipate, and actually executes. The document is a specification for a process. The human is the processor. Without the human, the document is inert, just a collection of marks on a page describing a thing that isn’t happening. Every format we’ve invented to package human expertise — apprenticeships, books, standard operating procedures (SOPs), wikis, software documentation — has been a different way of describing work to a human who will then do it. That assumption just became optional. For the first time, the thing on the other end of the document can actually execute what the document says. Not interpret, summarize, or explain it — execute it. The manual is no longer waiting for a person to walk up and read it. It’s being read, right now, by something that can act on what it reads. The shelf isn’t a shelf anymore. It’s a queue. And that changes what it means to write something down.

Page 10

The Parallel Track: Teaching Machines to Understand Us While writing manuals for other humans, we were also teaching machines to read. Not read the way a person reads — not yet. But each generation of programmers figured out how to write instructions that looked a little less like what a machine wanted and a little more like what a human would naturally say. The history of computing, viewed from a certain angle (suspiciously nudged here to help me make this point), is a history of instructions getting more human. Every layer of abstraction we’ve piled on top of the raw silicon has pulled the language of programming one step closer to ordinary thought. In the 1950s, to tell a computer what to do, you wrote in machine code — long strings of ones and zeros, or the slightly more tolerable hexadecimal shorthand that mapped directly onto the chip’s instruction set. A line of the program might look like 10110000 01100001. You weren’t describing a task. You were flipping physical switches inside a box, in a language designed entirely around what the hardware could digest. If you made a typo, the machine didn’t misunderstand you, it did exactly what you told it to, which is almost always worse. By the late 1950s, assembly language arrived as the first real act of translation. Instead of 10110000 01100001, you could write MOV AL, 61h — “move the value 0x61 into register AL” Still cryptic, still one instruction per line, still deeply aware of the machine underneath. But for the first time, the instruction had a verb. A word you could read out loud. Programming stopped being the arrangement of switches and became, just barely, the writing of sentences. The sentences were in a language only a few thousand people on earth could speak, but they were sentences.

Page 11

Then came the high-level programming languages like FORTRAN in 1957 for scientific computing, COBOL in 1959 for business systems, ALGOL around the same period quietly seeding the syntax that nearly every modern language would inherit, BASIC in 1964 putting programming within reach of students and hobbyists, C in 1972 as the bedrock that operating systems and almost everything beneath them would be written in, and then the wave that defined modern software: C++ in 1985, Python in 1991, Java and JavaScript both in 1995. For example, a piece of code like print("hello") (which prints the word ‘hello’) doesn’t tell the CPU anything directly. It tells a compiler or interpreter what you meant, and that other program handles the translation down to the bare metal. A non-programmer reading if age > 18: print("adult") can roughly guess what’s happening. The instructions had stopped being written for the machine. They were being written for another human who happened to also be a programmer, with the machine quietly listening in. APIs (application programming interfaces) took the next step. By the 2000s and 2010s, you rarely wrote software from scratch — you wrote glue between services that other people had already built. POST /users {"name": "Ana", "role": "engineer"} isn’t code the way machine code is code. It’s a request, phrased almost like a note you’d leave on someone’s desk. You’re not telling a CPU what to do. You’re telling another system what you want, and trusting it to figure out how. The instructions had become declarative, closer to stating intent than dictating procedure. Look at what happened across those four eras. The instructions went from unreadable to readable to roughly understandable to something a non- programmer could squint at and mostly follow. Every generation, the language of programming moved one step away from the machine and one step toward the human. And every generation, the pool of people who could write working instructions for computers expanded — from a few hundred specialists in

Page 12

the 1950s, to millions of professional programmers by the 2000s, to anyone with a laptop and an afternoon by the 2010s. But there was still a wall. Even the most human-friendly API call isn’t something you’d ever actually say to another person. No one has ever turned to a colleague and requested POST /users {"name": "Ana", "role": "engineer"} and if they did, you’d know they’ve been sitting at their computer too long, and they need a break. The instructions were getting more human, but they hadn’t arrived at human, at least not yet. The final gap between structured code and ordinary language stayed stubbornly in place. Meanwhile, over on the other track, humans kept writing manuals for other humans. SOPs, wikis, playbooks, onboarding docs, the whole library of expertise we talked about in the last section. Two formats of written instruction, developing in parallel for half a century. One kind of document, written for machines, that slowly got more human. Another kind of document, written for humans, that had always been human from the start. Two tracks, running alongside each other, never quite touching. They were about to. The Collision: Prompting On November 30, 2022, the two tracks finally converged (again, sort of). OpenAI released ChatGPT, and for the first time, anyone with an internet connection could write an open-ended instruction in ordinary English — across essentially any domain — and get back something useful without needing to endless scroll through links and webpages. The instruction didn’t have to look like MOV AL, 61h or POST /users or even print("hello"). It could look like “explain the 2008 financial crisis to

Page 13

me like I’m a smart twelve-year-old,” and a response would appear, and it would be, against all odds, pretty good. The separate tracks of machine code and ordinary language had finally converged, closing a 70-year gap, at least in a narrow sense. The instructions written for machines and the instructions written for humans collapsed into the same format: plain language, stuff you could say to a coworker without them batting an eye. ChatGPT reached a million users in five days2. A hundred million in two months3. Google’s global search traffic dropped nearly 8%4 over the following year as people started asking machines the kinds of questions they used to type into a search bar. The thing you typed into a computer, and the thing the computer could understand and answer directly were suddenly the same thing. And almost immediately, people discovered that how you typed it mattered. Prompting Becomes a Discipline If you asked (or “prompted”) ChatGPT to “summarize this article,” you got a summary of the given article. It’s fine, nothing special. If you asked it to “act as a senior magazine editor, read the following article and write a three-sentence summary that captures the thesis, the strongest evidence, and the author’s conclusion. Be direct. Don’t hedge,” you got something noticeably better. Same model. Same article. Dramatically different output. The only variable was the framing of the request. This idea that you could get better outputs from these models by pragmatically crafting better prompts was new. And it spawned a somewhat sketchy discipline — prompt engineering — that dominated the next two years of AI discourse. A cottage industry of techniques emerged all aimed at coming up with a systematic hack to improve the prompt for the AI to get dramatically better responses. A few select techniques: Few-Shot Learning (Brown et al., 2020) gives the model examples before asking for your thing. Chain-of-Thought Prompting (Wei et al., 2022) tells

Page 14

the model to think step by step. Self-consistency (Wang et al., 2022) samples multiple answers and takes the majority vote. Tree of Thoughts (Yao et al., 2023), ReAct (Yao et al., 2022), Reflexion, and Self-Refine are all clever hacks for squeezing more reliability out of a system that was brilliant but slippery. Most of those techniques will feel dated by the time you read this, and that’s fine. What mattered wasn’t any specific trick. What mattered is what the whole discipline quietly established — three things that everything else in this book rests on. First: The quality of the output is directly correlated with the quality of the input. Before prompting became a practice, there was a prevailing assumption that a language model was a kind of oracle — either it could do the thing or it couldn’t. Prompt engineering revealed that the same model, with the same underlying capabilities, could produce wildly different outputs depending on how you framed the request and what you placed inside of it (the context). The quality of the output was a design problem on the input side. Second: These models could follow instructions. Not only could you get good responses, but you could also get these models to follow specific instructions like “Summarize this content, then identify the key points, then list them as bullet points”. Third: Improving the quality of an AI system became something a non- engineer could do. Before prompting, making an AI model work better for your use case meant training a new one — a process that required specialized hardware, large datasets, and the kind of knowledge you get from a PhD, not a weekend. Prompting

Page 15

turned performance improvement into something you could do at your desk in ten minutes. Write a prompt. Read the output. Notice what’s wrong. Rewrite the prompt. Try again. The feedback loop was crude but accessible. For the first time, the person with domain expertise — the lawyer, the analyst, the PM, the teacher — could improve the AI system without going through an engineer and produce equally powerful workflow automations. A lot of people realized early that prompting was a skill not a trick. Practitioners discovered that structured, deliberate prompting dramatically improved output quality, one of the most prominent at the time was Riley Goodside who became famous for tweeting about his experiments with very structured and deliberate prompts that would automate all sorts of programming work. A useful way to frame prompt engineering is as a search or navigation process over a space of possibilities. AI Engineer Charles Frye captures this more evocatively in a well-known lecture, describing a “prompt as a portal.”5 François Chollet offers a similar definition: “Prompt engineering is the process of searching through program space to find the program that empirically seems to perform best on your target task.”6 The Ceiling Although prompt engineering transformed the way we interact with AI, it still has a clear ceiling. No matter how carefully you wrote the prompt, you were still asking the model to describe work, not to do it. You could prompt a model to explain how to process a customer return, draft the apology email, and outline the refund policy. You could not prompt it to actually issue the refund. You could prompt it to describe the SQL query that would pull your Q3 revenue. You could not prompt it to run the query. The model could walk you to the edge of the task with extraordinary eloquence and then stop

Page 16

because the task required reaching into a system the model had no way of touching. This is the gap between intelligence and agency. Between knowing and doing. Prompting, for all its sophistication, could never be the mechanism through which we close this gap, because it operates entirely inside the model’s text-generation loop. There was no mechanism for the model to click a button, hit an API, run a script, or send a file. The model was a brain in a jar: Extraordinarily capable inside the jar and yet completely sealed off from everything outside it. However, the gap between knowing how to do something did get narrower. For the first time in history, a machine could describe almost any task in fluent human language. But describing the task and performing it are not the same thing, and the distance between them — the last mile that has always separated expertise from execution — was still there. To close it, the model would need hands.

Page 17

Closing the Gap, Part One: Tool Calling So, a large language model (or LLM for short) by itself can’t check your calendar, nor query your database or even send a message. All it can do is produce more text. That’s fine if you just want a bad poem about the meaninglessness of life, but not so good if you want to get stuff done. To go beyond this flatland of text-in, text-out, we needed a bridge, something that could take this ability to produce appropriate responses and translate it into real-world action. That bridge arrived in February 2023, not even three months after the release of ChatGPT. The Paper That Changed Everything In February 2023, researchers from Meta AI and Universitat Pompeu Fabra published a paper called “Toolformer: Language Models Can Teach Themselves to Use Tools.”7 The core finding was striking: you could show a language model a handful of examples of text indicating how to use an external system (e.g: wikipedia, translation..), and the model would learn to produce similar requests on its own whenever it needed help from an outside tool. What Toolformer demonstrated was that these models, despite having no understanding of what a “tool” actually is, could learn a pattern: when I encounter a problem I can’t solve with text alone (like a math problem, or a question about today’s date, or a fact I’m not sure about), I should produce a specially formatted sentence that signals “go ask an external system for help.” This simple idea planted the seed for what came next. From Research to Product: OpenAI’s Function Calling On June 13, 2023, OpenAI took this idea — where models could now produce text that would be converted into action (running a specific program) — and developed something called: “function calling”. They released updated versions of GPT-4 and GPT-3.5 Turbo, specifically

Page 18

trained8 to recognize situations where a function9 should be used and then to produce clean organized text outputs that could be used to trigger that function through traditional code. This capability became known as function calling, and later rebranded into tool calling: you describe available tools as JSON schemas10 (essentially a standardized way of saying “this tool is called X, it takes these inputs, and here’s what each input means”), the model then generates a structured request (meaning: “call this function with these arguments”), your code executes it, and the result feeds back into the model. Simple mechanism with a profound implication: the brain in a jar got its first connection to the outside world. FUNCTION CALLING VS TOOL CALLING If you follow the AI space, you’ll notice that people use “function calling” and “tool calling” interchangeably. There’s a reason for that: the concept was rebranded. OpenAI’s original June 2023 API used a parameter called “functions” to describe the capabilities you gave the model. By December 2023, they deprecated that parameter and replaced it with a new one called “tools.” The name change wasn’t cosmetic. “Function” implies a narrow, code- centric capability — you’re calling a programming function. “Tool” is a broader, more accurate metaphor. A tool can be a web search, a code interpreter, a file reader, a database connection, or yes, a function. The shift in language reflected a shift in ambition: models weren’t just calling functions anymore; they were using tools, the way a craftsperson reaches for different instruments depending on what the job requires. Other providers — Anthropic11, Google, open-source projects — adopted “tool calling” as the standard term, and that’s what most of the industry uses today. Tool calling example

Page 19

To make tool calling concrete, imagine you’re building a simple travel assistant. You want the AI to be able to check the weather in a destination city when someone asks. Here’s what happens, step by step, also shown in Figure 1-1: Step 1: You describe the tool to the model. Before the model even sees the user’s question, you give it a description of what tools are available. Think of this like handing someone a menu of capabilities. You’re saying: “Here’s what you can do beyond just talking.” For our travel assistant, you’d describe a tool called “get_weather” and explain that it takes a city name as input and returns the current weather conditions. This description is written as a JSON schema. The key idea is that you’re writing a menu item with a name and a description of what it needs. Step 2: The user asks a question. A user types: “I’m thinking about visiting Lisbon next week. What’s the weather like?” Step 3: The model decides to use a tool. Instead of guessing at Lisbon’s weather (which it can’t know, since its training data has a cutoff date), the model recognizes that this is a situation where the “get_weather” tool would be helpful. So instead of producing a normal text response, it produces a with structured request: call get_weather with the argument city = “Lisbon”. Here’s the critical part: the model does not actually check the weather. It has no ability to connect to the internet or run code. All it does is produce a structured piece of text that says “I think this tool should be called with these inputs.” It declares intent. It’s like a doctor writing a prescription — the

Page 20

doctor doesn’t compound the medication, they write down what should be done, and the pharmacist fulfills it. Step 4: Your code executes the function. Your application — the code you’ve written around the model — sees this structured request, calls the actual weather API, and gets back: “Lisbon, 22°C, partly cloudy, 15% chance of rain.” Step 5: The result goes back to the model. Your code feeds the weather data back into the model’s context. Now the model has real, current information to work with. It responds to the user: “Lisbon looks great next week — 22°C and mostly sunny with just a small chance of rain. You might want to pack a light layer for evenings.” Figure 1-2. Five-step tool calling loop This five-step loop — describe the tools, receive a question, model requests a tool, code executes it, result feeds back — is the beating heart of function