Markdown and the encoding of skill
Nicolas Bustamante recently wrote a piece on vertical SaaS defensibility that blew up on X. It’s worth reading the whole thing. But one passage stuck with me.
Traditional vertical software encodes business logic in code. Thousands of if/then branches, validation rules, compliance checks, approval workflows. Hardcoded by engineers over years... and not just any engineers. You need software engineers who actually understand the domain, which is rare.
LLMs turn all of this into a markdown file.
Read that again. Decades of carefully encoded (and coded!) domain knowledge — the kind that required engineers who actually understood healthcare billing, or freight logistics, or insurance underwriting — collapsed into a text file.
Foundation models are particularly good at reading, understanding, creating and updating markdown files.
Skills - a standard introduced by Anthropic on October ‘25 - use this file format to package specific know-how. At the center of every Skill sits one file: SKILL.md.
A Skill is basically a folder that teaches an agent how to handle a specific task or workflow. Build an Excel model. Prepare a marketing report. Refactor Python code. The folder can hold instructions, domain knowledge, scripts, reference files — whatever is needed to get the job done effectively.
If this weren’t enough, Skills aren’t always loaded. They’re summoned on demand.
Whenever the request description matches the Skill’s capabilities and definition, it gets pulled into the session. When it doesn’t match, it stays out of the way.
This means that an AI tool can draw from hundreds of Skills — general-purpose and custom — without stuffing them all into memory at once. The context window stays clean. The answers stay sharp.
Also, they can be packaged up into Plugins. A combo of Skills, Agents, MCP servers and Hooks (automation triggers that run on events like file save or task completion).
Most people haven’t paid attention to this yet. Skills remain one of the most under-appreciated primitives in the space — even as nearly every major AI platform has quietly adopted the same pattern for packaging capabilities.
If you think about it, a markdown file is just a text file with some formatting. Anyone can read one. Anyone can edit one. Anyone can audit one. You don’t need to be an engineer. That’s the real shift. The person who understands healthcare billing can now write the Skill herself. The freight logistics expert doesn’t need a developer to translate his knowledge into code. Domain expertise goes straight into the file, and the model picks it up from there.
Specialization used to be enshrined in the codebase. Now it lives in documents anyone can edit.
Updating your business logic used to mean a sprint, a backlog ticket, and a deploy. Now it means editing a text file.
However, I think there is something else going on here.
The immediate temptation is to equate these markdown files with a way to encode SOPs (standard operating procedures) and document business workflows. And yes, Skills are that.
But they go further. They don’t just encode what to do. They encode how it should look and feel.
---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
license: Complete terms in LICENSE.txt
---
<< SKIPPED FOR CONCISIVENESS >>
## Frontend Aesthetics Guidelines
Focus on:
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.The example above is part of a Claude Skill, developed by Anthropic themselves, that teaches the model how to properly design frontend digital interfaces. Not just “put a button here” — the visual principles, the stylistic cues, the design sensibility behind the decisions. They’ve built others that teach the model how to create a PowerPoint, build a financial model, or write a Product Requirement Document.
If you read the markdown again you’ll notice that it isn’t a checklist. It’s trying to transfer taste.
So, is it markdown, maybe in combination with other techniques, the ultimate mechanism by which we can encode what looks good? What feels right? What separates competent from elegant?
I think it is. Not perfectly. Not always. But more than most people realize.
It only really works if you can explain the thing. If you can describe it clearly enough — the principles, the patterns, the reasoning behind the choices — the model can pick it up and apply it consistently.
The hard part isn’t the AI. It’s us. It’s our ability to encode in language the why and how.
Professional intuition. Artistic judgment. The feeling that a layout is “off” without knowing why. The sense that a strategy will work without listing the reasons.
Try writing that down in a markdown file. Most experts can’t articulate what they know — they just do it. That’s always been true. Long before AI entered the picture.
So the bottleneck isn’t whether the model can read and apply taste and judgment. It’s whether we can explain ours.
One cannot help but wonder how far the combination of Skills, JSON, reference documents, scripts, subagents and tools can get us in encoding human judgment and taste.
But most likely, it is our own limitation in describing the most nuanced aspects of what we do that will set the limits of the possible — not the AI capabilities.