My Weird Prompts · Daniel Rosehill

Agentskills.io Spec: From Broken YAML to Production Skills

April 6, 2026·21 min·1 clip
The description field is for agent routing, not for human-readable instructions.
1. My Weird Prompts covers the Agentskills.io specification for cloud code skills and the problem of broken YAML. 2. Herman Poppelberry and Kohn host the episode, with Daniel’s prompt shaping a line-by-line forensic walkthrough and workshop. 3. The episode asks how to turn the spec into a production-ready skill instead of a “vibe coding” guess. 4. The directory itself must be a kebab-case container, and its name must match the frontmatter `name` field. 5. `skill.md` is the mandatory entry point, while `scripts`, `references`, and `assets` sit beside it for progressive disclosure. 6. The frontmatter schema centers on five non-negotiable fields: `name`, `description`, `version`, `author`, and `triggers`. 7. The `name` field is described as the unique identifier in Claude Code’s tool registry, with 64-character and lowercase limits. 8. The `description` field is framed as a discovery signal for Claude Code, not as user-facing documentation. 9. `version` must use semantic versioning, such as `1.0.0`, and the triggers field currently supports slash commands. 10. A trigger in YAML must also have matching instructions in `skill.md`, or the skill is considered malfunctioning. 11. The allowed tools field is presented as a security control that pre-authorizes specific actions and forces confirmation on others. 12. Herman says a skill that tries to run an undeclared bash command will pause for manual confirmation. 13. The episode rejects XML tags in frontmatter and warns that tabs are not allowed in the YAML block. 14. The hosts say overscoping a skill into one huge file spreads the agent’s attention too thin. 15. A Docker Manager example shows a minimal viable skill built around `skill.md`, a `containers` slash command, and a helper script. 16. The helper script is described as returning structured JSON, because the hosts say Claude parses JSON more reliably than ASCII tables. 17. The workshop recommends the wizard pattern, where the agent presents running containers and waits for confirmation before stopping one. 18. The episode also mentions `ismeta`, subagents, and a validation tool called `claudeskillsvalidate` for checking syntax and required fields. 19. The tone is technical and instructional, with back-and-forth explanations and concrete file-level examples. 20. Listeners who write agent skills, YAML configs, or Claude Code tools will get the most from it, while casual listeners may skip the detailed spec walk-through.

As heard by us

A practical YAML repair guide for people shipping agent skills that need to load.

My Weird Prompts turns Agentskills.io specification talk into a practical repair guide for cloud code skills that will not load. Korn and Herman stay on the faults that matter, from missing fields and two-space indentation to XML tags in front matter and the way one overscoped…

Read the full review in PlayNext →

Why you'd press play

When one bad tab can break the whole skill file.

Read the full recommendation in PlayNext →
Listen to the show on