Problem

The skill-creator built-in skill has a description that reliably fails to trigger when an agent is editing or refactoring existing skills, rather than creating new ones from scratch.

Current description:

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

The words "packaging" and "designing" read as end-of-process / blank-slate creation activities. When an agent is mid-task refactoring an existing skill (e.g. splitting a large SKILL.md into SKILL.md + references/REFERENCE.md), it does not match this description against its active frame of "I am fixing [domain X] behavior" and skips the skill entirely.

Observed consequence

In a recent session, an agent was explicitly asked to refactor two internal skills (hermes, hive-dispatch) — splitting them into a procedures-only SKILL.md and a companion reference file. The skill-creator skill was never loaded. As a result:

1. The agent placed REFERENCE.md in the skill root instead of the spec-required references/ subdirectory
2. The agent added SKILL.md-style frontmatter to the reference file (invalid — name must match the parent directory name, and reference files aren't skills)
3. File references in SKILL.md used ./REFERENCE.md instead of references/REFERENCE.md

All three issues are caught by the skill-creator guidance and the AgentSkills spec — but neither was consulted because the skill never triggered.

Root cause

Meta-skills have a triggering handicap. The agent's attention is on the object-level task domain ("fix Hermes"), not the meta level ("I am currently authoring a skill file"). Meta-skill descriptions need unusually concrete trigger language to punch through.

Additionally, the agent arrived with a pre-formed plan ("split the file") rather than a discovery task. Skill-creator's value proposition leans toward discovery (understand → plan → init → edit → package), making it feel like overhead when the edit is already decided.

Suggested fix

1. Improve the description to cover edit/refactor explicitly:

Create, update, or refactor AgentSkills. Use when: creating a new skill from scratch, editing or improving an existing SKILL.md, restructuring a skill's layout (splitting content, adding reference files, reorganizing scripts/assets), or validating a skill against the AgentSkills spec.

2. Add an early trigger heuristic in the body:

Add a note near the top of the SKILL.md body: "If you are about to write to any SKILL.md file or create/move files within a skill directory — you are doing skill authoring. Follow this guide."

3. (Optional) Consider a filesystem-level trigger if OpenClaw supports auto-loading a skill when certain file patterns are opened for editing.

References

• AgentSkills specification — defines references/ subdirectory layout, frontmatter constraints, naming rules
• Relevant spec excerpt: "Skills should be structured for efficient use of context... Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context."