Documentation is where good intentions go to die.
I know this because I've written plenty of it. Step-by-step guides, onboarding wikis, checklists, runbooks - all carefully structured, all thoroughly ignored. Not because people are lazy, but because documentation solves the wrong problem. It assumes people will go looking for answers before they start working. They won't. They'll start working, get stuck, and then either ask someone or figure it out the hard way.
This is the gap that AI tools promise to fill - but most teams are filling it wrong. They drop Copilot or Claude into the workflow, write a CLAUDE.md file, maybe set up an MCP server, and call it a day. The tools are powerful, but without structure, they're just faster ways to do the wrong thing.
What if instead of writing documentation that nobody reads, you built AI skills that meet people exactly where they get stuck?
The Pull vs Push Problem
Documentation is a "pull" system. The developer has to:
- Realize they need help
- Know that documentation exists
- Find the right document
- Read and understand it
- Apply it to their specific situation
Every step is a point of failure. In my experience, most people fail at step 1 - they don't even realize they're about to go down the wrong path until they're already deep into it.
A skill is a "push" system. Knowledge comes to the person at the moment they need it, in the context of what they're doing right now. No searching, no reading, no guessing. The skill knows what step you're on and gives you exactly what you need to move forward.
This isn't a theoretical distinction. It's the difference between a map on the wall and a GPS in your car. Both contain the same information. One of them actually gets you where you're going.
The Skill Layer: Task - Workflow - Step - Skill
Most engineering teams have a set of recurring task types. Not individual tickets, but categories of work that follow roughly the same pattern every time. Integration with an external system. Migration of a legacy service. Onboarding a new data source. Setting up monitoring for a new component.
Each of these task types can be decomposed into a workflow - a sequence of steps that, when followed, reliably produce a good outcome. And each step in that workflow is a place where someone can get stuck, forget something, or waste time figuring out something that the team already knows.
This is where The Skill Layer comes in. It's not a new process - it's a layer you add on top of your existing workflow decomposition:
Task Type (recurring category of work)
└── Workflow (sequence of steps)
└── Step (concrete action)
└── Skill (AI assistant for this specific step)
The key insight is that the skill layer is where AI stops being a generic tool and becomes a teammate who knows your processes.
A Real Example: Integration with an External System
Let me walk through a task type that most teams deal with regularly - integrating with a third-party system. Here's a typical workflow:
- Prepare design doc
- Implement integration
- Implement integration tests
- Set up regression daily test job
- Prepare documentation
- Handoff
Six steps. Straightforward on paper. Now let's zoom into just the first one - "Prepare design doc" - and see what it actually involves:
- Investigate 3rd party system documentation and contracts
- Investigate prerequisites, security setup, supported auth types, available SDKs
- Investigate limitations, UI vs API differences
- Communicate with owners and ask for test data
- Do a PoC and play around (console app, cURL, Postman/Bruno collection)
- Negotiate API contracts with affected teams/stakeholders
- Go through checklist for "new integration proposal"
- Compose design doc with all collected data, aligned with checklist
- Get feedback and sign off
Nine sub-steps for one step out of six. And here's what's critical - most of these sub-steps have nothing to do with writing code. They're research, communication, negotiation, and documentation. These are exactly the areas where people get stuck the most and where AI can provide the most leverage.
Where People Actually Get Stuck
Let me map the pain points:
Step 1 - Investigate docs: "Where's the documentation? Is this the latest version? Which endpoints are relevant to our use case?" The developer spends 40 minutes searching Confluence and Slack history when an MCP server could surface the right docs in seconds.
Step 2 - Investigate prerequisites: "What exactly should I check? Did I forget something?" Without a checklist, people check what they remember to check. They miss auth type constraints, rate limits, or SDK version requirements that bite them two weeks later.
Step 3 - Investigate limitations: "The API doesn't support batch operations, but I didn't find that out until I was halfway through implementation." UI vs API capability gaps are a classic trap that a skill could surface upfront.
Step 4 - Communicate with owners: "I sent a message, they didn't reply, and I moved on to something else." This is the most common failure mode I see. Not a technical problem - a human one. No follow-up, no escalation path, no template for what to ask.
Step 5 - PoC: "I don't know where to start. What auth flow should I use? What's the simplest thing I can build to validate the integration?" Decision paralysis at the starting line.
Step 6 - Negotiate contracts: "I didn't realize Team X needed a different payload format." Missing stakeholders from the conversation is invisible until it's expensive.
Step 7 - Checklist: "What checklist?" The most honest and most common response.
Step 8 - Compose design doc: "I'm starting from scratch again." Every design doc is a blank page when it doesn't have to be.
Step 9 - Get feedback: "Who should review this? Where do I post it?" Routing and communication overhead on top of the actual work.
Three Types of Skills
Looking at these pain points, a pattern emerges. Skills for workflow steps fall into three categories:
Research Skills (gathering and structuring information)
These handle steps where the goal is to collect and understand data. For the integration example, that's steps 1-3 - finding documentation, checking prerequisites, mapping limitations. A research skill connects to your knowledge base through MCP, applies team-specific filters, and delivers a structured summary instead of raw search results. The developer gets "here's what you need to know" instead of "here's where to look."
Communication Skills (facilitating human interaction)
These handle steps that require reaching out, following up, and coordinating. Steps 4 and 6 in our example. A communication skill generates context-appropriate messages, sets follow-up reminders, suggests escalation paths when there's no response, and identifies stakeholders based on integration type. This is where AI provides perhaps the most unexpected value - not replacing communication, but making sure it actually happens.
Assembly Skills (composing artifacts from collected data)
These handle steps where everything comes together into a deliverable. Steps 7-9 - applying checklists, composing the design doc, routing for review. An assembly skill takes the outputs from research and communication steps and structures them into the team's expected format. The design doc isn't generated from nothing - it's assembled from everything the developer already gathered.
The Granularity Trap
There's a tempting shortcut here: why not build one big "integration skill" that handles everything? Or a general-purpose "research skill" that works across all workflows?
This is the granularity trap, and it leads you right back to the documentation problem. A skill that tries to cover too much ground becomes generic - and generic means the developer still has to figure out which part applies to their current situation. You've just replaced a wiki page with a chatbot that gives vague answers.
The Skill Layer only works when skills are step-specific. A skill for "investigate 3rd party documentation" is fundamentally different from a skill for "investigate prerequisites." The first one needs to know where docs live and how to extract relevant endpoints. The second one needs a checklist of security, auth, and SDK concerns specific to your team's standards. Merging them into one "investigation skill" dilutes both.
That said, step-specific skills don't have to be built from scratch every time. General-purpose capabilities - searching the knowledge base via MCP, generating a message draft, applying a template - can and should exist as building blocks. The difference is that these general capabilities are consumed by step-tailored skills, not exposed directly to the developer.
Think of it like functions in code. You wouldn't hand a developer a generic httpClient and say "integrate with the payment provider." You'd build a PaymentService that uses httpClient internally but exposes a domain-specific interface. Same principle: the step-specific skill is the interface the developer interacts with. General capabilities are implementation details underneath.
Step-tailored skill: "Investigate 3rd party docs"
├── uses: MCP search (general capability)
├── uses: Document summarizer (general capability)
└── adds: Team-specific filters, known doc locations,
output format matching the design doc template
Why This Works Better Than Documentation
The traditional approach: write a wiki page called "How to Integrate with External Systems" that covers all of this. The page exists. It's thorough. Nobody reads it.
The skills approach changes the dynamic in three ways:
Contextual activation. The skill knows which step you're on and gives you exactly what's relevant. No scrolling through a 15-page document to find the paragraph that applies to your situation.
Reduced cognitive load. The developer doesn't need to remember the process. The skill guides them through it. Mental energy goes toward the actual problem - understanding the external system - not toward remembering what to check next.
Protection against omissions. Didn't do a follow-up? The skill reminds you. Missed a stakeholder? The skill surfaces them. Forgot the checklist exists? The skill pulls it up automatically. Documentation can tell you what to do. Skills make sure you actually do it.
How to Start
You don't need to skill-ify your entire team's workflow on day one. Here's a practical starting point:
1. Identify your top 3 recurring task types. Not the unique, creative work - the patterns. "Every quarter we do X." "Every new client requires Y." These are your candidates.
2. Map the workflow for the most painful one. Write out the steps. Be specific. "Implement feature" is not a step - "investigate API docs, set up auth, write adapter layer" are steps.
3. Find the step where people get stuck most often. Ask your team. It's usually not the coding step. It's usually research, communication, or "I didn't know X existed."
4. Build one skill for that step. Just one. Make it genuinely useful. Make it faster than figuring it out alone.
5. Measure the before and after. Not just time saved - also errors avoided, follow-ups that actually happened, stakeholders that weren't missed.
Once one skill proves its value, The Skill Layer sells itself. People will start asking "can we have a skill for step Y too?"
The Bigger Picture
The Skill Layer - Task, Workflow, Step, Skill - isn't just about making AI useful for engineering teams. It's a way of thinking about how AI integrates into any structured work.
The teams that will get the most out of AI aren't the ones with the best models or the most expensive tools. They're the ones that did the hard work of understanding their own workflows deeply enough to know where AI should plug in - and then built skills that make it invisible.
Because the best AI integration is the one nobody notices. They just notice that things work better.