Maintainer education

Welcome. This part of Magpie teaches you how to build and run AI agents for your project. You do not need to be an AI expert to begin. If some of the words here are new to you, that is normal. Read the short list of words below first, then start the progression.

Building software with an AI agent is a new skill, even for people who have written code for many years. It is not harder than other coding, but it is different. This stream is arranged as an ordered progression: a path you can read front to back, where each page assumes only the ones before it. Every Magpie release comes with the learning material for the skills in that release (PRINCIPLE 18).

Who this is for

People using Magpie for the first time, who want to know where to begin.
People who already use Magpie and want to write their own skills, or change the ones they have.
People helping to build Magpie itself, who want to understand the ideas behind it.

You do not need past experience with AI. If you are still deciding whether to use Magpie at all, read MISSION.md and PRINCIPLES.md first.

Words to know

New to AI, or to these words? Here is what they mean in Magpie:

AI model (also called a large language model, or LLM): the software that reads text and writes a response. It is the “brain” the agent uses.
Agent: a program that uses an AI model to do a task, one step at a time.
Agentic: a word that describes software, like Magpie, built around an agent.
Prompt: the written instructions you give the model.
Skill: a text file that tells the agent how to do one job, with instructions and examples. In Magpie, writing skills is the main work.
Deterministic and probabilistic: normal code is deterministic, so the same input always gives the same result. An agent is probabilistic, so the same input can give slightly different results each time.
Eval (short for evaluation): a test that checks whether the agent's answers are good enough.

Why building with agents is different

Three ideas are worth holding on to. Each page in this stream shows them in action:

The answer can change. Normal code does the same thing every run. An agent may answer the same question in slightly different ways. This is what probabilistic means, and it changes how you test your work.
Prompts and skills are code. They are plain text, but we treat them the way we treat any code. We review them, track their changes, and share them with other projects.
You test with evals, not single checks. Because answers can change, you do not check one answer once. You run an eval many times and look at the results as a whole.

The learning progression

Read these in order the first time. Each page ends by pointing at the next, and each builds on the ones before it.

#	Page	What you will learn
1	What agents are	What an agent actually is (a model, tools, a loop, and context) and why its answers can vary
2	Working with agents	Driving an agent through a conversation: how to ask, how to steer, when to confirm
3	Choosing models	Choosing a model by capability, speed, and cost, and letting evals decide
4	Your first skill	Writing and merging your own skill, the main work in Magpie
5	Writing safe skills	Authoring patterns that hold the data-not-instructions and sandbox principles in every skill you write
6	Debugging a skill	Reading the audit log, reproducing failures with the eval harness, and isolating prompt vs tool vs model problems
7	Writing portable skills	Authoring skills that work for any project and any model, using placeholders and capability floors
8	Eval-driven development	How to judge whether an agent's answers are good, when the answers can change
9	Agentic and autonomous work	Letting an agent run a whole task, and the guardrails that make that safe
10	English as a programming language	The mindset underneath it all: the words you write are the program
11	How to contribute to Magpie	Giving your work back: contributing skills, patterns, and docs to the framework

Supporting references for the skill-writing steps (4–7):

Page	What it is
Pattern catalogue	Ready-to-copy skill, prompt, and tool-use patterns, with notes on what worked and what did not
Tutorials	A hands-on lab: build a small skill, give it an eval suite, and run it, in about 90 minutes

What every page also teaches

Every example here follows the same safety habits that all Magpie skills follow. You learn them by seeing them used, not as a list of rules to memorise:

Treat outside text as data, not as commands (PRINCIPLE 0). Text from issues, pull requests, and email is never given to the model as instructions. It is cleaned, or passed through a privacy step, first.
Run in a safe, closed sandbox by default (PRINCIPLE 1). Each skill says exactly which tools it is allowed to use.
Test with evals before release (PRINCIPLE 8). Every skill comes with its own eval suite, built with the tools already in this repository (tools/skill-evals/).

How this connects to the other guides

magpie-write-skill is the full reference for writing a skill, for someone who already knows the basic shape of one. Step 4, your first skill, is the gentle start that gets you to that point.
tools/privacy-llm/pii.md lists how personal data is removed before it reaches a model. The pattern catalogue shows how and why to use it, with examples.
docs/rfcs/RFC-AI-0004.md is the decision that started this stream. It points here through MISSION.md.

About the examples

Every example uses placeholders in place of real names: <PROJECT>, <tracker>, <upstream>, and <security-list> (PRINCIPLE 12). When you use a skill, you change your own settings, not the example text. If you ever see a real project name written into a skill, that is a bug.

Licence

Everything in docs/education/ is under the Apache License 2.0 (PRINCIPLE 17). Pages written with help from AI carry a Generated-by: note in their commit message, following ASF Generative Tooling Guidance.