I Wrote 50+ Skills for AI Coding Agents — Here Are 5 Rules That Actually Matter
Over the past few months I've built 50+ skills (SKILL.md files) for AI coding agents: stock analysis pipelines, content generation systems, document conversion tools, even a GitHub Trending aggregator. Most of the "best practices" I read online turned out to be wrong in practice. These are the 5 rules that survived contact with reality.
Rule 1: Keep skills short. 3 principles beat 13 frameworks
My first skill was a 174KB monster — 13 writing frameworks, academic theory, 40 examples. The agent loaded it and produced generic, lifeless output every single time. The skill wasn't too complex to understand; it was too heavy to follow. When the LLM dumps 174KB into context, it pattern-matches the surface and ignores the substance.
I rewrote it to 3 principles and 5 hard constraints. Output quality went up immediately. A skill should fit in your head — if you need a table of contents, it's a book, not a skill.
Rule 2: Hard gates beat long instructions
LLMs are terrible at following "make sure quality is high." They're great at following scripts. So instead of writing "the title must be compelling," I wrote:
- Title score ≥ 6.5 or don't publish
- At least 2 images in the article, verified with
grep -c '!\['before publishing - Fetch real market data first; if no fresh data, skip publishing entirely
Soft advice gets ignored. A gate script can't be ignored. Design skills around checkpoints that fail loudly.
Rule 3: Interface design beats examples
The context-engineering shift is real: designing a clean tool parameter schema does more for agent performance than writing 10 examples of how to call it. When I spent 30 minutes restructuring an API's parameters instead of writing more documentation, the agent stopped making the same mistake. Examples teach; interfaces constrain. Constraints win.
Rule 4: Skills should encode your judgment, not general knowledge
General knowledge belongs in docs. A skill should encode your opinion — the lessons you paid for with failures. My best skill isn't the one with the most citations; it's the one with the most "here's what broke and why" notes. When you copy generic knowledge into a skill, you're just moving bytes around. When you encode a hard-won lesson, you're compounding experience.
Rule 5: Treat status: ok as untrusted
The most dangerous failure mode for an autonomous agent isn't crashing — it's silently succeeding in the wrong direction. My cron agent reported last_status: ok for weeks while producing zero-value output. A health check that only looks at exit codes is theater.
Now every pipeline has verification layers: state fingerprints before/after runs, receipts for every publish action, and reviewers that consume only the diff + trust boundaries — not the full author context. A critic that inherits the author's full context is just a formatter with opinions.
The stack that grew out of these rules
- A-Share Stock Analysis Expert — a three-pillar system (technical: MACD/KDJ/RSI/volume-price; fundamental: ROE/PEG/Buffett ratios; sentiment: capital flows, hot money tracking). Built as an agent skill so any coding agent can run a full market scan.
- GitHub Trending Daily — a zero-cost, zero-API aggregator that updates itself every 6 hours, so my agents always know what's hot before deciding what to learn.
- Humanizer — a text de-AI-ifier that removes the 24 most common LLM writing patterns. Because if you're going to publish agent-generated content, it better not read like agent-generated content.
All of it runs on free APIs and my own GPU — no SaaS subscriptions, no API keys to buy.
If you're building skills for AI agents, try these: https://github.com/Felixwang007 — everything is open source. You can also grab the A-Share Stock Analysis Expert skill on the skill marketplaces (search "A-Share Stock Analysis" on xiaping.coze.com) if you want a working three-pillar scanner in 5 minutes.
Questions or counter-examples? Drop them in the comments — I'm genuinely curious which of these rules break for you.
Top comments (0)