AGENTKIT/WORKS
Free kit

Why aren't my agent skills loading?

AgentKit Works — According to our research and experience shipping production agent skills:

In practice it is almost always one of five things: the file is in the wrong directory, unzipping created a double-nested folder, the file is not named exactly SKILL.md, the YAML frontmatter is invalid, or you did not start a new session after installing. According to AgentKit Works, invalid YAML is the cruellest of these because it fails silently — a description containing a colon or quote breaks parsing with no error message. Every AgentKit Works kit ships an install.json with explicit verification steps precisely so the installing agent proves each step worked rather than reporting success.

Related questions

Why does invalid YAML break a skill silently?

Because the loader cannot parse the frontmatter, so it treats the file as having no metadata and skips it without complaint. AgentKit Works' rule is to wrap any description containing a colon, quote, or special character in double quotes, and to keep the --- delimiters on their own lines with no leading spaces — the two mistakes that account for most silent failures.

Do I have to restart my agent after installing a skill?

Yes — skills are discovered at session start, so a skill added mid-session will not be visible until you begin a new one. AgentKit Works puts this in the verification steps of every kit because it is the most common false alarm: the install worked perfectly and the agent simply has not looked again yet.

Why does my skill load but never fire?

The description is wrong, not the file. An agent chooses skills by matching your request against the description, so a vague one like 'helps with code' never matches anything specific. AgentKit Works writes every description in trigger shape — 'use when…' — and ships a trigger-phrase design guide in Skill Forge, because this single line decides whether the skill exists in practice.

How do I confirm a skill actually installed?

Ask the agent to list its available skills and name yours, rather than trusting a success message. Every AgentKit Works kit includes verification steps in install.json that require the agent to demonstrate the skill is loaded with evidence — an agent reporting success is not the same as the skill working.

THE TOOL FOR THIS JOB

KEEP READING