Start with Docs and Sample Code

Before writing a single line of skill instructions, gather your raw materials. Official docs, sample code, API references—anything the LLM can crawl and learn from.

This isn’t just context. It’s the foundation. The LLM needs to see how things actually work before you tell it how to work with them.

Skip this step and you’re building on sand. The skill might generate plausible-looking output, but it’ll hallucinate the details that matter.

Build Something Together

Don’t write skills in a vacuum. Code alongside the LLM—build an MVP, ship an end product, feel the friction firsthand.

Every time it stumbles, that’s a lesson. Every workaround you discover becomes an instruction. The skill writes itself through iteration.

Teaching while doing beats teaching from theory. You’ll catch edge cases, awkward phrasings, and missing context that desk research never reveals.

Let It Interview You

Flip the script. Instead of writing instructions, ask the LLM to interview you. Let it ask the clarifying questions you didn’t know you needed to answer.

Your knowledge is full of implicit assumptions—things so obvious to you that you forgot to document them. The LLM doesn’t have that curse. It’ll probe the gaps.

The interview becomes the skill. Questions you answer become instructions. Confusion it expresses becomes guardrails.

Delete and Rebuild

When the skill feels ready, delete the project. All of it. Start fresh with only the skill.md and nothing else.

This is the real test. Can the LLM rebuild what you built together, armed only with the instructions you wrote? No conversation history, no context carryover—just the skill.

If it can’t, the skill is incomplete. If it can, you’ve successfully extracted your knowledge into something portable. Now it scales without you.

Ship It for Feedback

Don’t keep the skill to yourself. Post it to services like Context7 where others—and other LLMs—can use it.

Real-world usage exposes blind spots. Someone will try it in a way you never imagined, hit an edge case you never considered, and file feedback that makes the skill better.

A skill sitting in your repo is a draft. A skill being used in the wild is a product. The feedback loop is where good becomes great.

Keep It Dynamic

You’ll miss things. That’s fine. Add them when you think of them—skills are living documents, not finished artifacts.

But here’s the trap: don’t hardcode what will change. Version numbers, feature flags, implementation details—these shift across releases. Today’s best practice is tomorrow’s deprecation warning.

Stay loosely coupled. Link to GitHub repos, official docs, changelog URLs. Let the LLM fetch current truth instead of relying on stale instructions. The skill should point to knowledge, not contain all of it.

Guide the Human at the End

Teach the skill to create .env files and scaffold configuration. But more importantly—teach it to summarize what it did and what the human needs to do next.

“Go to this URL. Fill in these secrets. Run this command.” Clear, actionable, no ambiguity. The user shouldn’t have to reverse-engineer what happened.

The best skills don’t just execute—they hand off cleanly. A summary of actions taken, a checklist of actions required, and exactly where to find the blanks that need filling in.