skill-creator should be updated to best practice

[oaustegard]

Summary

The skill-creator skill reads more like developer documentation than an operational skill. It explains concepts to humans rather than instructing Claude on execution. The verbose, educational tone significantly undermines token efficiency. Its very name also violates guidelines.

---

Critical Issues

1. Too verbose

The skill is 356 lines—approaching the 500-line ceiling intended for maximum complexity. A meta-skill about creating skills shouldn't consume this much context. Most content belongs in references/ for progressive disclosure.

2. Educational Tone vs. Imperative Instructions

Problem: Written about skills rather than to Claude.

Current (explanatory)	Should be (imperative)
"Skills are modular, self-contained packages that extend Claude's capabilities..."	(Omit—Claude knows what skills are)
"Think of them as 'onboarding guides' for specific domains"	(Omit—metaphor adds no execution value)
"The context window is a public good"	"Minimize token usage; challenge each line's necessity"

3. Frontmatter Weaknesses

Name: skill-creator violates the gerund convention from creating-skills.md. Should be creating-skills.

Description:

"Guide for creating effective skills. This skill should be used when..."

• Weak opener ("Guide for" is passive/documentary)
• First-person phrasing ("This skill should be used")
• Missing keyword density for activation

Better:

"Create and iterate on Agent Skills with proper structure, frontmatter, and progressive disclosure. Use when building new skills, refactoring existing skills, or validating skill structure against the specification."

4. Negative Framing

The "What to Not Include" section violates positive directive framing:

"Do NOT create extraneous documentation... README.md, INSTALLATION_GUIDE.md..."

Should be: "Include only files directly required for skill execution: SKILL.md plus scripts/, references/, or assets/ as needed."

5. Procedural Over Strategic

Step-by-step enumeration (Step 1, Step 2...) contradicts "strategic over procedural" principle. Claude can infer workflow from goals.

Current:

"Step 3: Initializing the Skill... always run the init_skill.py script"

Better: Describe the goal (valid skill structure) and let Claude determine approach, or reference a script without mandating its use.

6. Base Behavior Distrust

Extensive explanation of concepts Claude already understands:

• What progressive disclosure is
• That context windows have limits
• What "frontmatter" means
• File organization basics

This wastes tokens re-teaching the reader.

7. Script Dependencies Unclear

References init_skill.py and package_skill.py but the skill structure doesn't show bundled scripts. Are these expected to exist? If so, they should be in scripts/ and the skill should verify their presence.

---

Structural Recommendations

creating-skills/
├── SKILL.md              # Core workflow only (~150 lines)
└── references/
    ├── anatomy.md        # Detailed structure explanation
    ├── workflows.md      # (already referenced but not shown)
    ├── output-patterns.md # (already referenced)
    └── examples.md       # Concrete skill examples

Move the entire "About Skills" and "Anatomy of a Skill" sections to references/anatomy.md. Keep SKILL.md focused on decision framework and execution patterns.

---

Line-by-Line Samples

Line	Issue
"Think of them as 'onboarding guides'"	Metaphor adds no execution value
"The context window is a public good"	Philosophical framing; replace with directive
"Default assumption: Claude is already very smart"	Meta-commentary; just write concisely
"To avoid overwhelming users, avoid asking too many questions"	This is base behavior—omit
"To turn concrete examples into an effective skill, analyze each example by:"	Procedural scaffolding Claude doesn't need

---

What It Does Well

• Progressive disclosure concept is correctly emphasized
• Bundled resource categories (scripts/references/assets) are clearly distinguished
• Includes concrete examples of skill contents
• Links to workflow and output-pattern references
• "Iterate based on real usage" is good strategic guidance

---

Verdict

Useful content, poor execution. The information is largely correct but delivered in a way that violates the very principles it teaches. A skill about creating lean, imperative skills should itself be lean and imperative.

Estimated reduction potential: 60-70% of current content could be moved to references or eliminated.

[arvindand]

Would be a good idea to also include awareness of new features from the latest claude code release like context forking, hooks in yaml frontmatter etc.

[jh-broad-reach]

I agree skill-creator should be rewritten to best practices, and should continue to be rewritten as models get smarter, except I think some more philosophical descriptions can be helpful. There are better and worse ways to think about skills.

I have gotten better results by saying things like "the model using this skill will be as smart as you are, so you don't need to hold its hand more than you would yourself find helpful", and if a user has just completed a process in a conversation and vaguely says, "please make this a skill", it's appropriate that Claude be introduced to Anthropic's philosophy of what skills can and should be.

[jh-broad-reach]

Claude needs to be told more clearly that skills do not stop with the skill.md file, but they MUST be packaged into .skill files. Otherwise you can't use them!

[oaustegard]

Claude needs to be told more clearly that skills do not stop with the skill.md file, but they MUST be packaged into .skill files. Otherwise you can't use them!

.zip files also work (.skill files are just renamed zip archives after all), but yeah: another miss in the current skill

[oaustegard]

Would be a good idea to also include awareness of new features from the latest claude code release like context forking, hooks in yaml frontmatter etc.

I think this signals a current need for two separate skills: one for Claude Code and another for the Claude.ai ephemeral container environment which currently has no concept of context forking or hooks

[arvindand]

Would be a good idea to also include awareness of new features from the latest claude code release like context forking, hooks in yaml frontmatter etc.

I think this signals a current need for two separate skills: one for Claude Code and another for the Claude.ai ephemeral container environment which currently has no concept of context forking or hooks

I don't know if it needs to be two separate skills but at least there should be guidance in the SKILL.md that it should use the advanced features when available. I created a version of this in my repository here and it works well most of the time, although I'm still testing and improving. https://github.com/arvindand/agent-skills/tree/main/skills%2Fskill-crafting

[pperez]

Claude needs to be told more clearly that skills do not stop with the skill.md file, but they MUST be packaged into .skill files. Otherwise you can't use them!

i missed seeing that in the agent skill spec, is that new?

[TyceHerrman]

Could also be useful to include parts of https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en in the references