1. I'd Rather Be Writing
2. AI
3. Skills

Three hurdles preventing skill adoption

If you make a skill yourself, you know its origin and utility. But can you make a skill that others will use? Several factors prevent writers from embracing and using the skills made by others:

• Lack of awareness that the skill exists. Many tech writers are just unaware that the skills exist. It helps if the organization has a monorepo where agents can search for SKILL.md files in a single place. Even so, with thousands of files, agents might be highly swayed by skill names or descriptions and overlook skills that are otherwise more helpful.
• Irrelevance of part of the skill. Tech writing tends to be idiosyncratic. One TW’s processes in one group differ just enough from the next person that it’s hard to share a skill. For example, in one analysis I did, I found 38 different release notes skills in my company. We all do release notes just a little differently, though there are common patterns. The same goes for many other things as well, from table formatting preferences to API overviews and more.
• Megaskills combine too many miscellaneous tasks. Some skills function as megaskills that do a variety of tasks, from editing to moving files to reviewing content and more. This might be a personal checklist a tech writer has for a particular doc set. The problem, however, is that this same grab-bag of tasks might not fit other writers who don’t have the same needs in aggregate. A writer might look at the skill and reject it because 20% feels irrelevant or misguided. Skills instead should focus on a specific task and do it well.
• Lack of trust in the skill. Before TWs set a skill loose on their content, they want more assurance about what the skill will actually do, and how well. Skills should have evaluation components that test the skill, giving the writer confidence in the skill’s quality. Granted, eval files can be easily manipulated to pass tests, making the skill look high quality even if the skill doesn’t work. Likewise, eval files can be poorly written or conceived, resulting in failing scores even for skills that do the job fantastically.

To overcome some of these hurdles, skills should adopt a modular structure. Each skill should perform a single task. That task should be named and described in a clear way, removing any confusion about what it does. I’ll expand on modularity in the next section.