Learning path map
Detailed content
🧱 Skills and subagents: what they are
The two components that turn Claude Code into a factory: a skill (an on-demand reusable capability) and a subagent (isolated work with its own context). When to use each one and why they become assets.
A capability Claude Code loads when needed: a SKILL.md file with instructions and references. Teach it once, use it whenever the trigger fires.
Each repeated Factory task (diagnose, generate a document) becomes a skill. You stop re-explaining and gain consistency.
On demand · SKILL.md · reuse · triggered by description.
A separate Claude instance with its own context window, system prompt, and tools. It receives a task, works independently, and returns only the result.
Researching a company fills the context. A subagent isolates that mess and gives you only the essentials — the parent stays clean.
Isolated context · system prompt · own tools · returns summary.
Skill = a capability the main agent gains (generating PPTX). Subagent = a separate worker for a mission that consumes a lot of context (scanning the web).
Choosing the wrong one costs context and time. The simple rule prevents overengineering.
Skill vs. delegation · context cost · “in the same thread” vs. “separate thread.”
A SKILL.md file with frontmatter (name + description) at the top and the body in Markdown with the steps. The description is what triggers the skill.
Writing the right description determines whether the skill gets used. It's the most important and most overlooked piece.
Frontmatter · name · trigger description · body with steps.
Skills live in .claude/skills/ (from the project) or ~/.claude/skills/ (personal). Subagents stay in .claude/agents/. Each one in a folder with its file.
Knowing where it is helps Claude Code find the resource. Personal = applies to every project; project-level = goes with the repo.
.claude/skills · .claude/agents · project vs. personal scope.
Each skill and agent is a piece you build once and reuse every time. Together, they form the Factory’s machinery—your arsenal.
It’s the "minimum input, maximum output" thesis turning into code. The effort stays in building, not delivery.
Reusable asset · composition · arsenal · near-zero marginal cost.
🎯 Build your first skill (diagnostico-ia)
From trigger to packaging: define the description that triggers it, write the deterministic body, attach the T2 cheat sheets, test, iterate, and version. At the end, a skill that spits out a mini-diagnosis.
The frontmatter description explains when to use the skill. "Use it to assess the AI maturity of a company described in text."
If the description is vague, the skill never triggers. A good description = strong verbs + concrete triggers.
Trigger · action verbs · “use when” · specificity.
The Markdown body lists the steps: research the company, score maturity from 1-5, list 3 quick wins, suggest a 30/60/90 roadmap.
Numbered, specific steps produce repeatable output. Vague instructions produce a different result every time.
Numbered steps · determinism · fixed output format.
The skill points to supporting files (the maturity and quick-win cheat sheets you distilled in T2), loaded only when needed.
References give the skill consulting-level rigor without bloating SKILL.md. Lazy RAG in action.
Supporting files · on-demand loading · lean context.
Run the skill with a real company and check: did it trigger on its own? Does the output include maturity, quick wins, and a roadmap?
A real-world test reveals whether the description triggers and whether the output is useful. Without it, it's just theory.
Test case · trigger · output check.
Adjust the description and steps based on the test, complete the skill folder (SKILL.md + references), and get it ready to use.
The first version rarely gets it right. Iteration is the real work; packaging is what turns it into an asset.
Iteration · skill folder · ready for reuse.
Version-control the skill in Git (alongside the project) and, if you want, share it with your team or the community. History = traceable progress.
Version control protects your asset and lets you improve it without fear. Sharing builds authority.
Git · version · sharing · durable asset.
📄 The document skill (DocX/PPTX/Excel/PDF)
The polished deliverables aren't made from Markdown: they're made with Python. python-docx, python-pptx, openpyxl (with a color convention), and reportlab—wrapped in the gerar-entregavel skill. Markdown goes in; .docx and .pptx come out.
The client opens .docx, .pptx, .xlsx, and .pdf files — not raw Markdown. Generating them with code keeps everything formatted, repeatable, and on-brand.
It’s what makes the package feel like elite consulting. Without it, the deliverable dies in a text editor.
Final deliverable · formatting · repeatable · branding.
The library that creates .docx files: Document(), add_heading, add_paragraph, add_table and runs with color/bold. Generates the report and the SOW.
The final report and SOW are Word deliverables. Mastering docx means generating both without manual work.
Document · headings · tables · formatted runs.
Presentation(), slides by layout (0 title, 6 blank), text boxes, bullets, and RGBColor for colors. Generates the executive deck.
The deck is what closes the sale (T5). Watch out for the trick: it's RGBColor, no RgbColor.
Layouts · text boxes · RGBColor · executive deck.
Create .xlsx with real formulas (never hard-coded values) and the color convention: blue = input, black = formula, green = link, red = external, yellow = assumption.
The ROI calculator lives in Excel. The right formulas and colors help clients trust it and edit assumptions.
Formulas vs. values · 1-based indexing · color convention · ROI.
The Platypus method builds a story of elements (Paragraph, Spacer, Table) and ends with doc.build(story). Generates PDFs ready to send.
PDF is the universal delivery format. Platypus gives you style control without working with coordinates.
Platypus · story · build at the end · styles.
Wrap the four libraries into a skill: "given a Markdown file, generate the corresponding .docx/.pptx/.xlsx/.pdf". One reference for the whole package.
Becomes the Factory’s output engine. Markdown goes in from any prompt; a professional file comes out.
gerar-entregavel · wrapper · Markdown → file · output engine.
🕵️ Build your subagent (researcher & writer)
Two isolated workers: the company researcher gathers structured context, and the strategy writer drafts the deliverable. Reliable schema output, orchestrated with the skill—and when it’s worth parallelizing.
An agent file: frontmatter (name/description), system prompt (who it is), enabled tools, and the output format it should return.
Defining these four parts well is what separates a useful agent from one that returns loose text.
System prompt · tools · expected output · scope.
A subagent that receives a company name + description, researches it, and returns a CompanyContext: industry, stack, pain points, competitors, and AI initiatives.
It’s Phase 1 of the Factory turned into a worker. It isolates the heavy research and returns only clean context.
CompanyContext · isolated research · structured output.
Receives the CompanyContext + a framework (e.g., quick wins) and writes the deliverable in Markdown, ready for the generate-deliverable skill to format.
Separate research from writing. Each agent does one thing well, making it easy to test and improve.
Context + framework → draft · separation of roles.
Ask the agent to return JSON in a fixed format (a schema). Since the CompanyInput/ResearchOutput of the architecture: predictable fields.
Structured output is what makes it possible to chain agents. Free-form text breaks the pipeline; a schema doesn’t.
Schema · predictable JSON · chainable · contract.
The main agent calls the researcher-company, passes the context to the strategy-writer, and uses the gerar-entregavel skill to finalize the file.
It’s the Factory in miniature: research → writing → document. Orchestration is the builder’s job.
Orchestration · chaining · research→writing→document pipeline.
Run several subagents at the same time when the tasks are independent—for example, research 3 companies in parallel, with no shared state.
Parallelizing independent tasks saves time. But if one depends on another, the work is sequential — knowing the difference prevents bugs.
Parallel vs. sequential · independence · no shared state.