{"slug": "the-best-person-to-write-your-ai-agent-s-skills-probably-can-t-write-yaml", "title": "The best person to write your AI agent's skills probably can't write YAML", "summary": "A developer argues that AI agent skills are often mediocre because the people who know the workflows (support leads, ops managers, researchers) are not the ones writing the YAML files. The fix is to separate authoring from plumbing, letting experts write the substance while developers handle the technical setup, and to enforce versioning, testing, and review processes. The developer is building Contexory to automate these practices.", "body_md": "There's a quiet assumption baked into how most teams build agent skills right now: that the person who writes the SKILL.md file should be a developer. On the surface it makes sense. Skills live in `.claude/skills/`\n\nor `~/.openclaw/skills/`\n\n, they carry YAML frontmatter, and they get committed to a repo. That's developer turf.\n\nIt's also why so many agent skills are quietly mediocre.\n\nThe person who actually knows the workflow you're trying to encode (the support lead who knows how a refund really gets processed, the ops manager who knows the ten steps before an invoice goes out, the researcher who knows which sources to trust) is almost never the person editing the YAML. So a developer writes a plausible-looking skill from a secondhand description, and you get a skill that reads well and does the wrong thing in the cases that matter.\n\nIf you've followed the debate about AI and documentation, you've seen the argument that code can't capture intent. Skills have the same gap, one level up. A skill isn't code, it's procedural knowledge: the sequence, the judgment calls, the \"if the customer is enterprise, do this instead.\" That knowledge lives in the heads of the people doing the work, not the people who happen to own the repo.\n\nWhen repo access and YAML are the price of contributing, you filter out exactly the people whose knowledge would make the skill good. You optimize for who can commit, not who knows.\n\nThe fix isn't a nicer editor. It's treating skills the way you treat anything else that changes production behavior: with clear authorship, testing, versioning, and review. You can start doing most of this by hand today, no tooling required.\n\n**1. Write the description for the trigger, not for yourself.**\n\nA skill only helps if the agent actually reaches for it, and the `description`\n\nfield is what the model matches against. Write it in the words a user would use, not an internal label. \"Handles refunds, chargebacks, and 'where is my money' questions\" beats \"Refund Processing v2.\" Be specific about when it should fire.\n\n**2. Test that it fires before you ship it.**\n\nPaste in three or four real prompts a user would actually send and check whether the agent picks the skill. Most \"the agent ignored my skill\" problems are trigger problems you can catch in two minutes. Keep those test prompts next to the skill so anyone can re-run them after an edit.\n\n**3. Version them like code, because they are code.**\n\nA skill changes behavior, so a bad edit is a production bug. Keep skills in git, write a commit message that explains why the behavior changed, and make sure you can roll back. If you can't answer \"what changed in this skill last week, and who approved it,\" you're one careless edit away from your agent confidently doing the wrong thing for everyone at once.\n\n**4. Put a review step between authoring and rollout.**\n\nThis is the one people skip. A published skill reaches every agent and every user simultaneously, which deserves the same \"someone else looks before it merges\" bar as a code change. It doesn't have to be heavy: one reviewer, one approval, then it ships.\n\nHere's the shift most teams miss: separate authoring from plumbing. Let the person with the knowledge write the substance, and let the developer own the plumbing (the frontmatter, the allowed tools, the sync wiring). The expert shouldn't have to learn git to fix a wrong step, and the developer shouldn't have to become a support expert to ship a support skill.\n\nThe goal is simple: the people who know the workflow can change the skill safely, and nothing reaches every agent until someone has approved it.\n\nThat one principle, authorship by the expert plus review before rollout, does more for skill quality than any amount of prompt-tuning.\n\nI'll be upfront: I'm building [Contexory](https://www.contexory.com/?utm_source=devto&utm_medium=content&utm_campaign=launch) because I kept hitting this exact wall. It automates the four things above (collaborative authoring with the YAML handled for you, a trigger-test, version history, and a review/approval step) and then syncs the approved skill into OpenClaw and Claude Code. But that's not the point of this post. You can get most of the benefit with git, a handful of test prompts, and a rule that skills get reviewed before they ship. Do that first, whatever tools you use.\n\nIf you do want to see the automated version, it's live today, and it's on Product Hunt too, where honest feedback means more than anything:\n\nHow does your team handle this today? I'm especially curious whether anyone has gotten non-developers contributing real skills without it turning into a mess.", "url": "https://wpnews.pro/news/the-best-person-to-write-your-ai-agent-s-skills-probably-can-t-write-yaml", "canonical_source": "https://dev.to/contexory/the-best-person-to-write-your-ai-agents-skills-probably-cant-write-yaml-afm", "published_at": "2026-07-15 05:35:42+00:00", "updated_at": "2026-07-15 05:58:01.001734+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-products"], "entities": ["Contexory"], "alternates": {"html": "https://wpnews.pro/news/the-best-person-to-write-your-ai-agent-s-skills-probably-can-t-write-yaml", "markdown": "https://wpnews.pro/news/the-best-person-to-write-your-ai-agent-s-skills-probably-can-t-write-yaml.md", "text": "https://wpnews.pro/news/the-best-person-to-write-your-ai-agent-s-skills-probably-can-t-write-yaml.txt", "jsonld": "https://wpnews.pro/news/the-best-person-to-write-your-ai-agent-s-skills-probably-can-t-write-yaml.jsonld"}}