If you’ve been following my videos, you know I’m obsessed with vibecoding: using AI as a hyper‑fast junior dev while I stay the architect. The difference between chaotic AI code and production‑ready output is simple: skills + context.

In this post, I’m sharing, this is the written version of my video: the only vibe coding guide you need to go from chaotic AI output to production‑ready code.

  • The exact .md files I use to give my agent context
  • The list of skills I assign to it
  • And a quick, non‑mathy explanation of how LLMs actually use those documents (transformer architecture + the “Attention Is All You Need” paper)

Everything here is what I personally follow on my blog and in my projects.

The context layer: my .md files

Before I let the agent write a single line, I set up a small set of markdown files. These act as the project’s brain.

  • context.md
    One‑page brief: what we’re building, for whom, core features, tech stack, and constraints. This stops the agent from guessing the “why” behind the code.
  • design.md
    UI/UX guidelines: design system, component patterns, spacing, typography, and accessibility rules. I point it to references like Apple/Airbnb and a /design repo so it has actual taste.
  • architecture.md
    High‑level system design: services, data flow, key modules, deployment model, and scaling assumptions. This keeps the agent aligned with the overall structure.
  • conventions.md
    Coding standards: naming, folder structure, TypeScript rules, error handling, logging style. This is how I enforce DRY/KISS/YAGNI across AI‑generated code.
  • security.md
    Security rules: auth approach, secrets management, input validation, and what must always be human‑reviewed (auth, payments, crypto, PII).
  • api.md
    API contracts and patterns: route structure, request/response shapes, error formats, versioning rules. This makes the agent consistent instead of inventing random API styles.
  • data-model.md
    Database schema, entities, relationships, key queries, migration strategy. This is the single source of truth for how data is modeled.
  • testing.md
    Testing strategy: what to test, preferred frameworks, coverage expectations, example test patterns. The agent uses this to draft meaningful tests, not just boilerplate.
  • agents.md
    Agent‑specific rules: role, principles (DRY/KISS/YAGNI), do/don’t list, when to ask before changing things. This is where I tell it how to behave, not just what to build.
  • decisions.md
    Architecture decision log: key choices, alternatives considered, why we picked this path. This stops the agent from randomly re‑debating old decisions.

I also keep a /design repo with reference screenshots, patterns, and tokens, and I use resources like awesome‑design‑md to structure it.

The skill layer: what my agent “is good at”

I don’t just say “write code.” I explicitly tell my agent which skills it has. Here’s my current list.

Frontend & UI skills

  • frontend-ui-engineering
    Focuses on building clean, performant, accessible UIs with modern React/Next.js patterns. I use this for component architecture, state management, and responsive layouts.
  • web-quality-audit
    Runs a structured audit of performance, accessibility, SEO, and best practices. I ask the agent to use this before shipping any major UI change.
  • i-have-adhd
    Adapts explanations and task breakdowns for ADHD‑friendly workflows: short, clear steps, minimal context switching. This helps me stay focused when pairing with AI.
  • seo
    Ensures pages are SEO‑friendly: semantic HTML, meta tags, structured data, performance. I use this whenever I’m building content pages or landing pages.
  • clarify
    Forces the agent to ask clarifying questions when requirements are vague instead of guessing. This alone saves me from a lot of rewrites.
  • impeccable
    Pushes the agent to produce clean, consistent, well‑named code with minimal tech debt. Think “code you’re proud to show in a PR.”
  • optimize
    Focuses on performance and bundle size: smarter queries, caching strategies, code splitting. I use this when a feature feels slow or heavy.
  • polish
    Adds the final touches: micro‑interactions, spacing tweaks, error states, empty states. This is what turns “it works” into “it feels good.”
  • 12-principles-of-animation
    Applies classic animation principles to UI motion: timing, easing, feedback. I use this for onboarding flows, transitions, and interactive components.
  • Taste Skill
    Gives the agent a sense of visual taste: minimal, coherent, Apple/Airbnb‑style UI. Combined with design.md, this is how I get decent‑looking interfaces without a designer on every call.

Core engineering skills

  • The /code-review Skill
    Treats AI output like a PR: checks for bugs, edge cases, security issues, and alignment with conventions. I run this before merging anything non‑trivial.
  • The /ponytail Skill
    Enforces clean code principles like DRY, KISS, and readability as explicit rules for the agent. I use this to keep AI‑generated code simple, avoid over‑engineering, and make refactors obvious.
  • The /prototype Skill
    Fast, throwaway implementation to validate an idea or flow. I use this in early stages when I care more about learning than perfection.
  • The /improve-codebase-architecture Skill
    Refactors structure: module boundaries, folder layout, dependency direction. This is how I keep the codebase sane as features pile up.
  • The /diagnosing-bugs Skill
    Systematic debugging: reproducing issues, isolating causes, proposing minimal fixes. I use this when I’m stuck on a weird bug or flaky test.
  • The /resolving-merge-conflicts Skill
    Handles Git conflicts intelligently, preserving logic and tests. This is surprisingly useful when I’m juggling multiple feature branches with AI help.

How LLMs actually use my .md files (without the math)

This is the part most “vibecoding” guides skip: how the model is even capable of reading and using your documents.

The 2017 paper that changed everything: “Attention Is All You Need”

In 2017, a paper called “Attention Is All You Need” introduced the Transformer architecture. Before this, sequence models (like RNNs/LSTMs) read text word‑by‑word, which was slow and struggled with long‑range dependencies.

The big idea: throw away sequential processing and use attention instead. Let the model look at all tokens at once and figure out which ones matter most for each other. That single insight is why we have GPT, Claude, Gemini, Llama, DeepSeek, etc. today.

At a high level, the Transformer has:

  • Encoder stack – reads the input sequence and builds rich contextual representations.
  • Decoder stack – uses that context to generate output token by token (like a chat response or code).
  • Both stacks are made of identical layers with:
  • Multi‑head self‑attention – lets each token “attend” to multiple other tokens in parallel.

The core mechanism is Query, Key, Value (Q, K, V):

  • Query: “What am I looking for?”
  • Key: “What do I contain?”
  • Value: “What information do I pass on if I’m relevant?"

Attention computes how relevant each token is to every other token, then builds a weighted sum of values. This is how the model captures relationships like “this variable is used in that function” or “this pronoun refers to that noun” across long documents.

Modern LLMs are mostly decoder‑only Transformers (like GPT): they generate text one token at a time, using causal masking so they can’t “peek into the future” during training.

So how do my .md files fit into this?

When you paste your context.md, design.md, agents.md, etc. into the prompt (or use a RAG system to retrieve them), you’re doing two things:

  1. Turning your docs into tokens
    Your markdown is tokenized (split into subword pieces) and converted into embeddings – numerical vectors that represent meaning.
  2. Letting attention connect your docs to the task
    The model’s attention mechanism learns which parts of your documents are most relevant to the current question or coding task.
    • If you ask it to “implement a login page following design.md”, attention will weight the relevant sections of design.md higher.
    • If you say “follow security rules from security.md”, those tokens become important context for generating the code.

In 2026, most serious setups use a hybrid of:

  • RAG (Retrieval‑Augmented Generation) – retrieve the most relevant chunks from your docs at query time.
  • Long context windows – feed larger, coherent sections of your .md files so the model can reason across them, not just isolated snippets.

The result: the model isn’t just “guessing from its training data”; it’s grounding its output in your specs, conventions, and design rules. That’s why well‑structured .md files dramatically improve output quality.

  • Feed‑forward networks – do additional computation on those representations.
  • Residual connections + layer norm – keep gradients stable so deep models can train.

How I actually use this in practice

My workflow is simple:

  1. Spin up the .md files for a new project or feature.
  2. Tell the agent which skills to activate (e.g., “Use frontend-ui-engineering + polish + seo for this landing page”).
  3. Work in small slices: spec → plan → code → test → review → polish.
  4. Commit after each working slice; run /code-review before merging.

If you want, I can share a starter repo with these .md templates and a sample agents.md you can copy.

Resources I reference

If you’re vibecoding right now, try adding even 3–4 of these skills and 2–3 .md files. You’ll feel the difference in output quality within a week.