🛠️ Building a Skill and an Agent
The system prompt was just the beginning. Now you move up a level: you’re going to package a skill in a Skill (that triggers automatically via description) and, when the work calls for it, will go "hire" an agent with a clearly defined beginning and end. Let's look at the five layers of the agentic system, where each piece fits, and when parallelizing makes sense — with a real INEMA example at the end.
Detailed content
What a Skill is
So far, you’ve written prompts to use now, at hand. A Skill is the next step: you package a capability — "create a video," "make a comic book," "analyze a workflow" — so the AI can pull it in on its own when the request fits. You don’t paste the prompt every time; the skill stays saved and shows up at the right moment. The secret to a good skill lies in just two parts.
🧩 A skill is two things stuck together
Every skill has a description (the label that decides when she connects) and a body of instructions (what to do after that was connected). The description is the part the AI reads all the time to decide whether that request is “in scope” for that skill. The body is only read when it activates.
That’s why the golden rule: the description is the most important part. A flawless instruction that never fires is useless. Write the label with clear triggers — the actual words the user would use.
What it is
A little package with a name, a description rich in triggers, and a body of instructions (a SKILL.md) that teaches the AI to carry out that task from beginning to end. It’s like giving the AI a "recorded recipe": it recognizes the request by its label and follows the steps without you having to explain everything again.
Why it matters
Because a skill turns a prompt you paste every time into a capability that lives in your system. And because the number one failure point is the trigger: skills that "don't trigger" almost always have a vague description. Getting the label right is what separates a useful skill from one that sleeps forever.
name: video-explicativo description: Cria vídeos explicativos em PT-BR a partir de um assunto — roteiro, narração, cenas animadas e CTA. Use quando o usuário pedir "fazer um vídeo", "vídeo explicativo", "vídeo sobre X", "vídeo pra Shorts/Reels", "mini tutorial em vídeo", ou quando der um assunto e quiser um vídeo narrado pronto. Cobre roteiro, locução, animação, render e a CTA final.
Notice: the description says what it does and, especially, when to use — with the exact trigger phrases in quotes. That’s what makes the skill activate for the right request (and stay quiet for the others).
The 5 layers of an agentic system
A skill doesn't exist on its own. It's one piece of a larger whole — what people call Agentic OS: an agentic operating system, assembled in layers. Look at the stack above: five levels, from bottom to top, each building on the one below. Knowing this stack means knowing where everything you create will live.
1. Identity—the bedrock
The foundation of everything. Without it, all the layers above become “directionally fluffy.”
Who the system is, the data that grounds it, the goals. In the source video’s health example, that’s the DNA panel, the markers, the goals. "If the data isn’t organized, you build something cute that might help, but it isn’t tailored to you."
2. Rules & Hooks — the rails
What always applies, plus automations triggered by events.
Rules are the stable behavior ("truth over flattery"). Hooks are automatic triggers that the harness enforces at certain times — e.g., "after I edit a file, run the tests". The rule asks; the hook ensures.
3. Skills — the abilities
The middle layer: recipes triggered by the description.
Packaged skills that the system pulls in when the request matches — diet analysis, weekly summary, report extraction. This is exactly what you saw in topic 1: description that connects + body that executes.
4. Agents & Subagents — the roles
Workers with a defined role, beginning, and end.
A agent has its own role (e.g., "a general coach who reads my markers before responding"); subagents are specialists it calls (metabolism, training, supplementation). This is the layer where most people "jump the gun" — we return to it in topic 4.
5. Tools · MCPs · CLIs — the hands
The top: what actually touches the world.
Search the web, run code, write to a database (in the example, a Supabase with 13 tables), call an API. The layers below decide; this runs. Add a new tool only when the system really needs it.
The order is bottom-up
You build the system in layer order: first the identity (the data), then rules/hooks, then skills, and only then agents e tools as the use calls for. Anyone who starts with agents is building the roof before the foundation.
Agent vs. subagent
The words agent e subagent confused because they seem like the same thing. They aren't. The difference is simple: one agent is the worker who receives the mission; a subagent is a specialist who this agent calls in for part of the work—and returns only the result, without dumping the entire draft back.
Agent — the lead
Receives the task, keeps the thread, and decides the path. It’s who talks with you and makes sure the work gets finished. In the health example: the general coach that reads your markers before any response.
- •Has the context for the entire mission
- •Decide when to call a specialist
- •Puts the pieces together and delivers the result
Subagent—the specialist
It’s called by the agent for a specific slice, does only that, and returns a concise conclusion — not the pile of files it read. In the example: an expert in metabolism, another of training, another of supplementation.
- •See only the part assigned to you
- •Works in its own context window
- •Return the conclusion, not the draft
🧠 Why separating things works
The greatest benefit of a subagent is protect the owner’s context. When a task would mean scanning dozens of files or logs, the agent delegates: the subagent dives into it in own window and return with only the conclusion. The owner gets the answer, not the search clutter.
It's the same logic as in the real world: a director doesn't read every spreadsheet—they ask an analyst and get a summary. Each subagent is an analyst with a scope and a deliverable.
Rule of thumb
Skill = a recipe that runs automatically. Agent = a worker with a role. Subagent = a helper the agent calls for one part and that returns only the result. A skill is what; the agent is who.
When to “hire” an agent
Here’s the mistake the source video itself warns about: "a lot of people jump the gun by creating agents". The temptation is to build an army of agents right from the start, because it seems advanced. But an agent is justified only when there is a role with a clear line marking where it starts and ends. Without this boundary, you’ve created complexity, not capability.
📐 The “role with a start and end” test
- ① Can you name the role in one sentence? "The agent that does X." If you need a paragraph, the role still isn’t clear.
- ② Where does it start? What trigger activates this agent and not another?
- ③ Where does it end? What’s the deliverable that says “done”? Without a finish line, the agent becomes a bottomless pit.
✓ When it makes sense to create an agent
- ✓The role fits in one sentence, with a clear beginning and end
- ✓The task is mutually exclusive — it does not overlap with another
- ✓You’ve seen this work repeat itself in practice
- ✓There’s a concrete deliverable that signals “done”
✗ When it’s too early (skip the weapon)
- ✗You create the agent "because it seems advanced"
- ✗The rules still overlap — nothing is clearly bounded
- ✗The role only vaguely describes in paragraphs where it begins and ends
- ✗A simple skill would already handle the same task
The discipline, stated by the source itself
"It doesn’t make sense to add agents at the beginning, because I haven’t yet separated which rules should be mutually exclusive versus rules that overlap." Wait for the work if revealed. Create the agent when the role boundary becomes obvious — not before.
Parallelize subagents
Once you have subagents, you get a superpower: run several at the same time. When two tasks don’t depend on each other, there’s no reason to do them in sequence. That’s also a principle that cutting-edge systems themselves state: "independent calls with no dependencies between them go in the same batch" — in parallel.
⚡ The benefit of running them together
✓ Can be parallelized when…
- ✓The tasks are independent — none uses the other’s result
- ✓Each subagent has its own scope and deliverable
- ✓You want to cover several research areas at once
- ✓There’s no shared state that one can trample on in the other
✗ DON’T parallelize when…
- ✗Step B needs what step A discovered (it’s a chain)
- ✗Two agents would write to the same file at the same time
- ✗The order matters for the final result
- ✗It’s a single, small task—parallelizing is just overhead
The question that unlocks everything
Before dispatching, ask: "does the next step need the result of the previous one?" If no, send it along. If yes, is a chain — respect the order. Independent work in parallel, dependent work in sequence.
Real example: an INEMA skill
Enough abstraction — let’s open a real INEMA skill. The explanatory-video grab one subject and returns a narrated, animated, rendered video. It's the perfect example of Tool Contract (Technique 8): every pipeline stage has a trigger, prerequisite, and order— that’s what separates an agent that executes from one that fumbles around.
DISPARA quando: "fazer um vídeo", "vídeo sobre X", "vídeo pra Shorts" ① roteiro → escreve SCRIPT.md (beats do assunto) ② narração → gera os WAVs (TTS local) · pré-req: roteiro pronto ③ composição → monta as cenas animadas · pré-req: durações medidas ④ validar → lint + inspect (0 erro) · antes de renderizar ⑤ render → HTML → MP4 (16:9 e 9:16) REGRA DE OURO: a CTA do INEMA.CLUB é sempre a última cena.
Each step runs only after that the previous one delivered — narration needs the script, composition needs the durations. That’s the contract: when, in what order, with which prerequisite. Without it, the AI would try to render before any audio existed.
🧱 Where each layer appears here
Identity: the INEMA standard — PT-BR, premium dark amber, local voice. It's the bedrock the skill assumes.
Rule: "the INEMA.CLUB CTA is always the final scene" — non-negotiable, always applies.
Skill: the very thing explanatory-video, which is triggered by the trigger-rich description.
Agent: in a larger package (the "producer"), an agent orchestrates plan → direction → render, calling skills like this one.
Tools/CLIs: the local TTS, HyperFrames (HTML→MP4), FFmpeg — the hands that actually generate the file.
Where you can parallelize (and where you can't)
The two formats— 16:9 e 9:16 — they’re independent: they can be rendered in parallel. The pipeline itself (script → narration → composition) is a chain: each stage depends on the previous one, so it runs in sequence. Even within a skill, you separate what’s independent from what’s dependent.
⚠️ The blind spot: actually verifying
The step almost every pipeline handles poorly is verification. It's not enough for the skill to say "I rendered it." The contract needs to conclude with a verification clause:
- 1.The file exists in the right destination? (don't trust the exit code)
- 2.The lint passed with zero errors before rendering?
- 3.Narrate faithfully what happened—instead of saying “done” without checking.
🛠️ Hands-on: your deliverable
Before moving on, sketch yours. In 15 minutes, you’ll have the skeleton of a skill—and the clarity to know whether it needs an agent or not.
- 1 Choose a repetitive task of yours (write a post, summarize a report, put together a slide). Write the description with 3 to 5 trigger phrases — the actual words you'd use when asking.
- 2 List the pipeline in order: each step with its prerequisite (what needs to be ready beforehand). It’s your tool contract.
- 3 Apply the test from topic 4: is this a skill (a recipe that triggers) or asks for a agent (a role with a beginning and an end)? When in doubt, stick with the skill.
- 4 Mark which steps are independent (could run in parallel) and end with a line of verification: how you check that the output actually exists.
📝 Module Summary
- ✓A Skill é a description that triggers + the body that runs; the description is the most important part
- ✓The 5 layers of the Agentic OS: identity → rules/hooks → skills → agents/subagents → tools/MCPs/CLIs
- ✓Agent holds the mission; subagent handles one slice in its own context and returns only the conclusion
- ✓Hire an agent only when the role has a clear beginning and end — don't jump the gun
- ✓Parallelize what is independent; keep what is a chain in sequence
- ✓A real skill is a pipeline with a contract (trigger, order, prerequisite) that closes by checking the output
➡️ Next Module
2.7 — ✅ Verification and accurate reporting. You built the skill and designed the agent. Now for the piece that ties it all together: how to get AI to actually check that the work succeeded — and describe what happened without saying “done” in the dark.