MD vs skills structure for production AI agent

[claydegi]

Hey — I’m running a real AI marketing system in production (not demos)

I’m currently restructuring it by separating context vs how-to across MD files, and then grouping how-to into reusable skills

The goal is to move from a workflow that works (but still requires ~7–8 hours of manual coordination) to a more autonomous, task-based system

Biggest challenge: a lot of decision logic is still implicit and doesn’t map cleanly into skills or structured files

In your experience, what breaks first in this kind of MD + skills architecture when moving toward automation?

[TheDecipherist]

Good question — and the answer is pretty consistent across production AI systems: implicit decision logic is always what breaks first.

The specific failure mode: you have a workflow that works because you hold the context that bridges the gap between your MD files. The MD describes what to do, you supply the why and when. As soon as you try to automate that gap, you discover the bridge was never written down.

The symptom looks like this:

• Skills run correctly in isolation but produce wrong output in context
• Claude follows the how-to but misses a precondition that was obvious to you
• Two skills produce plausible-looking but contradictory outputs because they compute the same concept using different logic

What actually fixes it: make the implicit decision logic explicit in structured documentation before building the skills. This is the core idea behind MDD (Manual-First Development), which is covered in the companion starter kit:

👉 claude-code-mastery-project-starter-kit

The short version of the pattern:

1. Write a feature doc first — not a prompt, not a skill, a structured doc that specifies: what this does, what data it touches, what the decision rules are, what it depends on
2. Run a data flow analysis before building anything — for every value the skill will consume or produce, trace the full chain: where is it computed? how is it transported? is the same concept computed differently elsewhere? This is where implicit logic gets surfaced
3. Generate test skeletons from the doc — the tests define the finish line. If you can't write a test for it, the decision logic isn't explicit enough yet
4. Build the skill to pass the tests — not the other way around

The 7–8 hours of manual coordination you're doing is almost certainly you acting as the implicit decision layer. The path to autonomy is replacing yourself with documentation, not with more skills.

The starter kit has a /mdd command that runs this workflow end-to-end. The new Phase 2 (Data Flow & Impact Analysis) was added specifically because of a similar issue — AI building on top of existing data without verifying the computation chain.