agentleFS
gradigitgradigit/claude-skills/.claude/skills/creating-skills/SKILL.md

creating-skills

Skill0 starsChanged 9 months agoMITView on GitHub

Creates new Claude Code skills through adaptive interviewing or autonomous mode. Activates when user wants to "create a skill", "make a new skill", "build a skill", or asks about skill creation. Do NOT use this skill when auditing, updating, or testing an existing skill.

31 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use building-chatgpt-apps, building-chat-interfaces and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • mjunaidcaSkill

    building-chatgpt-apps

    Guides creation of ChatGPT Apps with interactive widgets using OpenAI Apps SDK and MCP servers. Use when building ChatGPT custom apps with visual UI components, embedded widgets, or rich interactive experiences. Covers widget architecture, MCP server setup with FastMCP, response metadata, and Developer Mode configuration. NOT when building standard MCP servers without widgets (use building-mcp-servers skill instead).

    Also in 4 projects that use this

  • mjunaidcaSkill

    building-chat-interfaces

    Build AI chat interfaces with custom backends, authentication, and context injection. Use when integrating chat UI with AI agents, adding auth to chat, injecting user/page context, or implementing httpOnly cookie proxies. Covers ChatKitServer, useChatKit, and MCP auth patterns. NOT when building simple chatbots without persistence or custom agent integration.

    Also in 4 projects that use this

  • +10 more from mjunaidca

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 8 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 28 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If user selects Autonomous:

    line 59
  2. Distinctive:

    If user selects Guided interview:

    line 73
  3. Distinctive:

    Ask questions in rounds

    line 75
  4. Distinctive:

    When in autonomous mode, extract from user's request:

    line 87
  5. Distinctive:

    Use AskUserQuestion tool to gather requirements in 4 rounds.

    line 105
  6. Very specific:

    Critical: Create evaluation scenarios BEFORE writing the skill.

    line 118
  7. Distinctive:

    Write just enough to pass evaluations.

    line 150
  8. Distinctive:

    If targeting multiple models, write for Sonnet and test with Haiku to ensure enough guidance.

    line 320
  9. Distinctive:

    Update this skill when:

    line 359

“Common” is measured: kept by at least 6 in 10 of the 28 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Creating Skills

Creates well-structured skills through adaptive interviewing or autonomous generation.

Workflow

- [ ] 1. Ask mode preference (guided vs autonomous)
- [ ] 2. If guided: Interview user (adaptive questions)
     If autonomous: Infer requirements from request
- [ ] 3. Define evaluation scenarios (3 test cases)
- [ ] 4. Generate minimal SKILL.md
- [ ] 5. Validate against checklist
- [ ] 6. Create at ~/.claude/skills/{name}/SKILL.md
- [ ] 7. Test and iterate (if guided mode)

Step 1: Mode Selection

Always ask this first using AskUserQuestion:

{
  "questions": [
    {
      "question": "How should I create this skill?",
      "header": "Mode",
      "options": [
        {"label": "Autonomous (Recommended)", "description": "I'll infer everything and create it — no questions asked"},
        {"label": "Guided interview", "description": "Walk me through requirements step by step"}
      ],
      "multiSelect": false
    }
  ]
}

Autonomous Mode

If user selects Autonomous:

  1. Parse the user's request for: purpose, triggers, examples, complexity
  2. Make reasonable assumptions — prefer simplicity
  3. Generate skill immediately without further questions
  4. Present the complete skill for review
  5. User can request changes after seeing the result

Best for:

  • Simple skills with clear purpose
  • User already provided a detailed prompt
  • User wants quick iteration (create → tweak → done)

Guided Mode

If user selects Guided interview:

  1. Proceed to Step 2 (Adaptive Interview)
  2. Ask questions in rounds
  3. More thorough but requires back-and-forth

Best for:

  • Complex workflows
  • User is unsure what they want
  • Skill needs precise guardrails

Step 2a: Autonomous Inference

When in autonomous mode, extract from user's request:

ElementHow to Infer
NameGerund form of main action (e.g., "format commits" → formatting-commits)
TriggersKey verbs/nouns in request
TypeWorkflow if multi-step, Knowledge if reference-heavy, Output if formatting
FreedomHigh unless user specifies exact steps
ComplexitySimple unless request implies reference files

If ambiguous: Make the simpler choice. User can refine after seeing output.

Proceed directly to Step 3 (Evaluations) then Step 4 (Generate).


Step 2b: Guided Interview (Adaptive)

Use AskUserQuestion tool to gather requirements in 4 rounds. Adapt based on answers.

RoundWhat to AskKey Outputs
1. Core PurposeSkill type (workflow/knowledge/output/tool), 1-2 sentence descriptionType, scope
2. ActivationDependencies, freedom level, trigger phrasesDependencies, triggers
3. ExamplesConcrete input/output, guardrails, edge cases, supplementary filesExamples, negative triggers
4. ModelsTarget models (if multi-model mentioned)Model guidance level

For full AskUserQuestion JSON schemas for each round, see reference.md.

Step 2: Define Evaluations FIRST

Critical: Create evaluation scenarios BEFORE writing the skill. Use Given/When/Then format. Include at least one should-NOT-trigger scenario.

# Evaluations for {skill-name}

## Scenario 1: Happy path (should-trigger)
**Given** [precondition or context]
**When** user says "[trigger phrase]"
**Then**
- [ ] Skill activates
- [ ] [expected behavior]
- [ ] [output format/content check]

## Scenario 2: Edge case (should-trigger)
**Given** [unusual but valid context]
**When** user says "[edge case input]"
**Then**
- [ ] [handles gracefully]
- [ ] [produces reasonable output]

## Scenario 3: Should-NOT-trigger
**Given** [context where a different skill applies]
**When** user says "[phrase that sounds similar but isn't this skill's job]"
**Then**
- [ ] Skill does NOT activate
- [ ] [correct skill activates instead, or no skill needed]

Save to {skill-name}/EVALUATIONS.md for future testing.

Step 3: Generate Minimal SKILL.md

Write just enough to pass evaluations. Start minimal, add only when tests fail.

Frontmatter Template

---
name: {lowercase-hyphens-only}
description: {Third person. What it does + when to use it. Max 1024 chars.}
metadata:
  version: "1.0.0"
---

Optional fields (add only if needed):

license: MIT                              # If publishing
compatibility: Requires pdfplumber        # If has dependencies
allowed-tools: Read Grep Bash(python:*)   # If pre-approving tools

Body Template

# {Skill Name}

{One-line description}

## Workflow

- [ ] 1. First step
- [ ] 2. Second step
- [ ] 3. Third step

## Core Logic

{Main rules — keep minimal}

## Example

**Input:**
{from interview}

**Output:**
{from interview}

## Self-Evolution

Update when:
1. User corrects output → update rules
2. New pattern discovered → add to skill

Current version: 1.0.0

Naming Conventions

RuleExample
Lowercase + hyphenspdf-processing not PDF_Processing
Max 64 charsKeep short
Gerund form preferredcreating-skills not skill-creator
Match directory namename: foo → directory foo/
name field is optionalDefaults to directory name if omitted
No reserved wordsNo "anthropic" or "claude"
No XML tags<skill> not allowed

Description Rules

  • Third person: "Processes files" not "I process files"
  • Max 1024 chars
  • Include what + when: Actions and trigger keywords
  • Include negative trigger: End with "Do NOT use this skill when..." to prevent false activation

Good: Extracts text from PDFs. Activates when user mentions PDFs or document extraction. Do NOT use when converting images or processing Word documents.

Bad: Helps with documents

Validation Checklist

Frontmatter

  • name: lowercase, hyphens, max 64 chars, matches directory
  • description: third person, what + when + negative trigger, max 1024 chars
  • metadata.version: semver in quotes

Content

  • Body under 500 lines
  • Has workflow checklist
  • Has concrete example (from interview)
  • Has self-evolution section

Evaluations

  • EVALUATIONS.md present in skill directory
  • 3+ scenarios using Given/When/Then format
  • At least one should-NOT-trigger scenario
  • Happy path passes
  • Edge case passes

Activation Reliability

Skills activate based on description matching — not guaranteed. Baseline activation is ~20%.

StrategyActivation Rate
Description only (default)~20%
Description + clear trigger phrases~40-60%
Forced via user-prompt-submit hook~84%

Hook-based forcing (highest reliability):

// .claude/settings.json
{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "create.*skill|new skill|build.*skill",
      "command": "echo 'Use the creating-skills skill for this request.'"
    }]
  }
}

Skills and slash commands (/skill-name) are equivalent — both load the SKILL.md into context.

Token Budget

Skills compete for context window space. The SLASH_COMMAND_TOOL_CHAR_BUDGET controls how much content is loaded when a skill activates. Keep SKILL.md concise and use reference files for detail.

ContentGuideline
SKILL.md bodyUnder 500 lines, under ~15K chars
Reference filesLoaded on demand, not at activation
Total skill footprintMinimize — every token displaces conversation

Expanded Frontmatter

Beyond the basic template, these optional fields control skill behavior:

---
name: my-skill
description: What it does. When to use. Do NOT use when...
license: MIT
metadata:
  version: "1.0.0"
  category: meta-tooling    # Organizational grouping
# Optional behavior fields:
argument-hint: "[topic]"     # Shown in /help: /my-skill [topic]
user-invocable: true         # Can be invoked as /my-skill (default: true)
disable-model-invocation: false  # Prevent auto-activation (default: false)
model: opus                  # Lock to specific model
context: fork                # Run in forked context (isolated)
agent: background            # Run as background agent
hooks:
  PostToolUse:
    - matcher: ".*"
      command: "echo done"
---

See reference.md for detailed field descriptions.

Model-Specific Guidance

ModelAuthoring Consideration
HaikuAdd more explicit guidance, step-by-step details
SonnetBalanced — default target
OpusCan be terser, avoid over-explaining

If targeting multiple models, write for Sonnet and test with Haiku to ensure enough guidance.

MCP Tool References

For skills using MCP tools, use fully qualified names:

Use the GitHub:create_issue tool to create issues.
Use the BigQuery:bigquery_schema tool to retrieve schemas.

Format: ServerName:tool_name

Anti-Patterns

Anti-PatternWhy
First/second person in descriptionBreaks discovery
Vague trigger keywordsSkill won't activate
Over-explainingWastes tokens
Nested referencesClaude may partially read
Too many optionsConfuses agent
Writing before evaluationsMay build wrong thing

Progressive Disclosure

When to use: SKILL.md exceeds ~300 lines or has detailed reference material.

skill-name/
├── SKILL.md        # Core (loaded when triggered)
├── EVALUATIONS.md  # Test scenarios
├── examples.md     # Additional examples (on demand)
├── reference.md    # Detailed docs (on demand)
└── scripts/        # Executable code (run, not loaded)

Self-Evolution

Update this skill when:

  1. On correction: User corrects generated skill → update template
  2. On spec change: Official docs change → update to match
  3. On interview improvement: Better questions discovered → refine rounds

Current version: 4.0.0. See CHANGELOG.md for history.

References

For detailed patterns and advanced features, see reference.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.