skill-creator: add design-phase guidance from internal skill-building lessons#674
Open
abe238 wants to merge 1 commit intoanthropics:mainfrom
Open
skill-creator: add design-phase guidance from internal skill-building lessons#674abe238 wants to merge 1 commit intoanthropics:mainfrom
abe238 wants to merge 1 commit intoanthropics:mainfrom
Conversation
…ill-building lessons Adds six sections to the Skill Writing Guide based on patterns documented in Thariq Shihipar's 'Lessons from Building Claude Code: How We Use Skills': - Skill type taxonomy (9 categories) during intent capture - 'Focus on What Claude Does Not Already Know' writing principle - Gotchas section as a first-class skill component - Setup and user config pattern (config.json) - Memory and data persistence guidance (CLAUDE_PLUGIN_DATA) - On-demand hooks as a design pattern - Distribution guidance (repo vs marketplace, context cost) These additions target the design phase of skill creation, which the current skill-creator handles well for eval/iterate but gives less guidance on.
Author
|
@ThariqS a gift for you here. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds design-phase guidance to the skill-creator skill based on the patterns documented in @thariqshihipar's article "Lessons from Building Claude Code: How We Use Skills".
The problem
The skill-creator is strong on the eval/iterate loop and description optimization, but gives less guidance during the design phase. Users jumping in to create a skill get great tooling for testing and benchmarking, but not much help thinking about what makes a good skill before they start writing one.
What this adds
Seven new sections, all integrated into the existing structure:
Skill type taxonomy (9 categories) added to the Capture Intent phase. Helps users identify what kind of skill they are building so they can pick the right patterns early.
"Focus on What Claude Does Not Already Know" as a writing principle. The most common waste in skills is restating things Claude would do anyway. This section coaches users to focus on the non-obvious stuff: internal conventions, edge cases, domain-specific patterns.
Gotchas section as a first-class skill component. The article calls this the "highest-signal content in any skill." Now explicitly recommended in the writing guide.
Setup and user config pattern (
config.json). Many skills need user-specific context (which Slack channel, which repo, credentials). This documents the check-on-first-run pattern so skills feel polished instead of asking the same questions every time.Memory and data persistence guidance. Skills can store state across runs, but data in the skill directory gets wiped on upgrade. This section documents the problem and points to
${CLAUDE_PLUGIN_DATA}as the stable alternative.On-demand hooks as a design pattern. The frontmatter reference mentions hooks exist, but this section explains when and why to use them, with concrete examples like
/carefuland/freeze.Distribution guidance. Repo-checked vs marketplace, and the context cost tradeoff that matters at scale.
What this does not change
The eval loop, benchmarking, description optimization, and all environment-specific instructions (Claude.ai, Cowork) are untouched. This is purely additive.
Why
I have been building and maintaining skills across multiple agent frameworks for a few months now. These gaps kept coming up. When Thariq published the article documenting the same patterns from Anthropic's internal usage, it felt like the right time to contribute them back upstream so others can skip the trial and error.
cc @thariqshihipar