erfankashani Posted on May 30 Designing Coding Agent Skills That Actually Work # vscodecopilot # runnerhchallenge # ai # agents I've spent the last few months obsessed with AI coding agents. Not just using them. Building alongside them and optimizing them for my use-cases. I've designed and tested various skills for agents like Claude Code, VScode Copilot, Codex, and Cursor, and I've watched closely to see where they hold up and where they quietly fall apart. And they do fall apart. Usually in the same way. The agent does great for three steps, then does something dumb on step four, it starts backtracking and analyzing went wrong, and by the time it figures out the issue, the conetxt window is almost full, leaving you with 3 what-have-I-done-so-far.md files instead of a task done. After enough of those moments, I stopped trying to make the agent smarter. I changed how I think about skill design entirely. This blog is about that shift, and the patterns that came out of it. The skill that taught me this The example I keep coming back to is a skill I built called confluence-publisher . The origin is boring but honest: I didn't have corporate access to a Confluence MCP server, so my agent had no native way to publish pages. Instead of waiting on IT, I built the bridge myself: a skill that takes markdown and publishes it to Confluence. I used this skill design as my sandbox for my new skill framework. Every pain point I'd hit with other skills showed up here too, so I used it to work out what actually makes an agent skill reliable. The full code is on GitHub if you want to follow along: 🔗 GitHub: link The mental shift Now to the part that changed how I work. When a skill misbehaves, the instinct is to constrain the agent : add more rules, more guardrails, more "do not do this" in the prompt. That's the wrong knob. You end up fighting the model. The better move is to constrain the tools , not the agent. Make the things the agent reaches for, the scripts, deterministic an
LIVE