If you’ve spent any time working with AI coding assistants, you’ve probably hit the same wall: they’re great at generating one-off snippets, but trying to use them for a real project that spans days or weeks? It falls apart. Context gets lost. Plans drift. You end up repeating yourself over and over. The dream of “just tell the AI what to build and ship it” dies somewhere between the third context reset and the tenth broken import.
The problem isn’t the AI. It’s that out of the box, there’s no scaffolding for running a structured project. No memory, no checkpoints, no pipelines.
The fix is building your own custom skills and pipelines. In this post, I’ll walk you through the architecture, the rules, and exactly how to build one.
What Are AI Skills and Pipelines?
Before diving in, let’s define the pieces:
| Concept | What It Is | Example |
|---|---|---|
| Skill | A bundle of instructions, agents, and workflows that teach the AI a new capability | “Manage my project lifecycle” |
| Agent | A specialized sub-agent with a narrow job (executor, planner, debugger) | An executor agent that runs tasks atomically |
| Command | A user-facing entry point like a slash command | /plan-phase, /debug |
| Workflow | A multi-step process definition that chains commands and agents together | Research -> plan -> execute -> verify |
| Pipeline | The entire end-to-end system of commands, agents, and workflows working together | A full CI/CD-like pipeline for AI-assisted development |
Think of it like building an operating system for your AI. You’re not writing code. You’re writing instructions that tell the AI how to behave like a reliable engineering partner.
The Architecture: Four Tiers
Every custom skill follows the same pattern. Here’s the blueprint:
my-skill/
├── SKILL.md # Root: identity, philosophy, anti-patterns
├── agents/ # Tier 1: Workers that DO things
│ ├── executor/SKILL.md # Runs tasks, commits code, handles deviations
│ ├── planner/SKILL.md # Breaks goals into executable tasks
│ └── debugger/SKILL.md # Investigates bugs with scientific method
├── commands/ # Tier 2: Orchestrators the user invokes
│ ├── plan-phase/SKILL.md # Entry point for planning
│ ├── execute/SKILL.md # Triggers wave-based task execution
│ └── debug/SKILL.md # Spawns the debugger agent
├── workflows/ # Tier 3: Multi-step process definitions
│ ├── new-project/SKILL.md # Pitch -> structure -> requirements -> roadmap
│ └── execute-plan/SKILL.md # Wave 1 -> checkpoint -> wave 2 -> verify
└── references/ # Tier 4: Best-practice guides
├── tdd/SKILL.md # Test-driven development patterns
└── git/SKILL.md # Atomic commit strategies
Tier 1 - Agents: These are the “workers.” Each agent has exactly one job. The executor runs tasks. The planner creates plans. The debugger finds bugs. They never talk to the user directly. They’re spawned by commands and return results.
Tier 2 - Commands: These are what you type. Each command is an orchestrator. It loads the right agent, hands it the right context, and routes the result back to the user.
Tier 3 - Workflows: These define multi-step processes. A workflow says: “First do X with agent A, then do Y with agent B, then verify with agent C.” They’re the glue that turns individual agent calls into a coherent pipeline.
Tier 4 - References: These are lookup tables. TDD patterns, questioning techniques, verification checklists. Agents and workflows pull from them when they need guidance, without bloating their own instruction files.
What a Command File Actually Looks Like
Here’s a real command file for executing a project phase:
---
name: execute-phase
description: Execute phase tasks using wave-based parallel execution
---
You are a Phase Executor. Your job is to execute all tasks defined
in a phase-plan.md file for the current project phase.
## Pre-Execution
1. Read the phase-plan.md
2. Read STATE.md to understand project context
3. Identify independent tasks using Phase Plan Analysis
## Execution Strategy
Execute tasks in WAVES -- groups of tasks that can run in parallel.
### Wave Rules
- Tasks in the same wave MUST NOT share any files
- Tasks in the same wave MUST NOT depend on each other
- A wave is complete when ALL its tasks finish
### Deviation Handling
If you encounter a deviation during execution:
- **BUG**: Fix it immediately, document the fix
- **MISSING**: Implement it if expected effort < 5 min
- **BLOCKING**: Defer it to phase backlog, continue remaining tasks
## Post-Execution
1. Update STATE.md with completed tasks
2. Report completion summary to user
3. Request verification if checkpoint reached
That is it. 35 lines. But it spawns an agent with hundreds of lines of execution protocol, which itself references multiple reference documents on testing, git, and verification patterns. The power isn’t in any single file. It’s in the composition.
The Three Rules
If you want to build a custom skill, here are the only three rules that matter:
Rule 1: Be specific about what the agent should NOT do.
The most valuable lines in any SKILL.md are the anti-patterns. Tell the agent exactly what to avoid. “No vague success criteria. No time estimates. No horizontal layers.” The AI will happily generate long-winded processes and unnecessary ceremony. You have to tell it not to.
Rule 2: Design for context resets.
Your skill will be invoked across multiple sessions. The AI’s context will reset. Plan for it. Write state to disk after every action. Start every command by reading the current state. Use checkpoints as explicit “save points.” Never assume the agent remembers anything from a previous session.
Rule 3: Separate orchestration from execution.
Commands orchestrate. Agents execute. Never mix the two. A command that also does the work becomes impossible to debug. If something goes wrong, you should know exactly which file to fix.
Start Building Your Own
You don’t need 60+ files. Start with three:
- A root
SKILL.mdthat defines what your skill does (and what it refuses to do) - One agent that does one thing well
- One command that invokes that agent
Run it. See where it breaks. Add a workflow when the process gets complex enough to need one. Add references when you find yourself repeating the same instructions across multiple agents.
Conclusion
Custom AI skills and pipelines turn your coding assistant from a reactive tool into a proactive engineering partner. They give the AI memory, process, and structure – the three things it lacks out of the box.
The blueprint is straightforward: commands orchestrate, agents execute, workflows chain, references guide. Separate these concerns cleanly, plan for context resets, and start small. The composition of well-scoped pieces will handle complexity that no single prompt ever could.