AI Agent Skills: The Markdown Files That Teach

Here's the thing about working with AI coding agents: they're smart, but they have terrible institutional memory. Tell Claude Code how you want your Python packages installed, and it'll do it perfectly. Start a new session five minutes later, and it's back to square one—no memory of your preferred workflow, your project structure, or that one specific way you need things done.

The traditional solution has been agents.md or claude.md files—basically instruction manuals that load with every session. But there's a problem: context windows are finite. Cram too much into that file and your AI agent starts struggling with the actual coding because it's spending mental energy parsing your novel-length setup guide.

Enter skills: markdown files that sit quietly in a .claude/skills directory until the agent actually needs them.

How Skills Actually Work

The concept is almost embarrassingly simple. A skill is a directory containing a skill.md file with three components: a name, a description, and whatever instructions you want to give.

NeuralNine demonstrates this with a Python package installation skill. The header looks like this:

---
name: Python package installation
description: Installing Python packages the right way
---

Below that, you write instructions: "Always use UV add, not pip install, to add packages. After that, always run UV Python freeze requirements.txt for compatibility reasons."

The clever part is what happens when you actually use the agent. When you tell it to "install pandas," it scans through all available skills, reading only the name and description fields. It sees "Python package installation, installing Python packages the right way" and thinks: yeah, this is relevant. Only then does it load the full skill content as context.

"What's going to happen now, and you're going to actually see this here, is the skill is loaded," NeuralNine explains in the demo. "You can see skill Python package installation was recognized as a useful skill. It was loaded, and now it does UV add pandas, same as before, and now it's going to do the pip freeze step as well, just because it's written in the skill."

This selective loading is the entire point. You're not jamming everything into one agents.md file that bloats every single interaction. You're creating a library of context that gets pulled in only when needed.

The LangChain Problem

The practical value becomes obvious when you look at fast-moving libraries. NeuralNine uses LangChain as the example—a Python library that reorganizes its API with alarming frequency. Code from a year ago uses LangGraph.prebuilt and create_react_agent. Current code uses LangChain.agents and create_agent. It's different enough that an AI agent working from training data will confidently write deprecated code.

The solution is a LangChain-docs skill that tells the agent: "LangChain changes its API very often. Code from 1 month ago might already be outdated. Always rely on the docs. Check how the thing you're trying to do is done in the latest docs today."

Without the skill, Claude Code cheerfully imports the old way. With the skill loaded, it does web searches first, checks current documentation, and writes code that actually works with the version you have installed.

Skills You Didn't Write

The other interesting angle here: you don't have to write all this yourself. Both Anthropic and OpenAI maintain skill repositories on GitHub with pre-built skills for common workflows. PDF processing, Docker commands, testing frameworks—someone's already documented the patterns.

These aren't minimal examples either. Production skills include multiple markdown files, conditional loading instructions ("if this situation, then look at forms.md"), and even executable scripts the agent can run instead of implementing everything from scratch.

There's even a skill-creator skill that lets the agent write new skills for itself. Tell it "create a skill for properly printing in Python code, always start print strings with XYZ," and it generates the skill.md file with examples of correct and incorrect usage. It's recursive and slightly unsettling, like teaching a tool to modify its own instruction manual.

When Automatic Detection Fails

The system isn't flawless. Sometimes agents don't automatically recognize which skill applies. NeuralNine shows this happening with OpenAI's models—the skill exists, but the agent doesn't load it.

The workaround is manual skill invocation: type /skills to see what's available, then explicitly call the skill with /Python-package-installation before your prompt. It's an extra step, but it forces the context you need.

There's also variation in how well different platforms handle web searches and external documentation fetches. Claude Code struggles with the LangChain docs skill in the demo—it loads the skill but doesn't fetch documentation cleanly. The same workflow in OpenCode works smoothly. These are implementation details that'll probably smooth out, but right now, they matter.

The Actual Innovation Here

What makes skills interesting isn't the markdown format—that's been around forever. It's the pattern of on-demand context loading based on semantic relevance. The agent looks at what you're asking it to do, decides which skills apply, and constructs its context window accordingly.

This solves a real problem with AI development workflows: the tension between giving the agent enough information to work effectively and not drowning it in irrelevant context that degrades performance. You can have dozens of skills defined—Docker workflows, API patterns, testing conventions, deployment procedures—without loading all of them into every interaction.

It's also reusable across projects. Create a skill once, copy the directory to new projects, and you've got consistent behavior without rewriting instructions. That's genuinely useful for anyone juggling multiple codebases with similar patterns.

The question is whether this pattern generalizes beyond coding agents. Could you use skills for writing assistants that need style guides? Research tools that need domain-specific context? Customer service bots that need policy documentation? The structure works; it's just a matter of whether other tools adopt it.

For now, if you're working with Claude Code or OpenAI's coding agents and you find yourself repeatedly explaining the same workflow, the answer is probably a skill. It's not revolutionary technology—it's just organized markdown files with smart loading. But sometimes that's exactly what solves the problem.

— Tyler Nakamura