In my experience building an open-source project using agent.md and skill.md, I’d say that many “agent skills” are essentially structured system prompts, but the surrounding configuration and orchestration matter more in practice.

One issue I’ve run into is that different models (e.g., Codex vs. Claude/Opus) often require slightly different configurations. This leads to duplicated files like .codex/skill.md and .claude/skill.md, which adds maintenance overhead.

For example, when working in non-English contexts, I need to ensure the AI doesn’t generate non-English inline comments. Constraints like this often have to be repeated across model-specific configs.

In my case, since enforcing English comments is a priority, I tend to put this in skill.md. Otherwise, I would place it in agent.md.

Because of this, I prefer using a single AGENTS.md as a global configuration layer. It’s simpler to manage and reduces duplication.

Honestly, a lot of them are.

We ran SkillCompass across 881 ClawHub skills and abt 46% scored poorly on functional depth, meaning they tell Claude what the skill is but never what to actually do. We kept seeing the same pattern: a name, a vague description, maybe a table that just repeated the skill name in every row.

Claude with the skill vs. Claude without it: behavior was basically the same.