Step 1: Understand the purpose

Before anything else, you MUST understand what the user wants the skill to do. This is the most important step — do NOT proceed without a clear answer.

Ask the user: "What should this skill do? Describe the task or workflow you want to automate."

If the user provided a skill name via $ARGUMENTS, acknowledge it, but still ask what the skill is for. A name alone is not enough context to generate a useful skill.

If the provided name does not start with docs-, prepend it automatically and tell the user you normalized it to the catalog naming convention.

Wait for the user's answer. If the response is vague (e.g., "help with docs"), ask follow-up questions until you have a concrete understanding of:

What problem the skill solves
What inputs it needs (files, URLs, arguments)
What output or side effects it produces

Step 2: Collect details

Once the purpose is clear, use AskUserQuestion to collect the remaining details (you may batch related questions):

Skill name: A short, kebab-case name that MUST start with docs- (e.g., docs-review-docs, docs-check-applies-to). Suggest one based on the purpose.
Category: Which category does this skill belong to? (e.g., authoring, review, workflow, testing)
Trigger: Should it be user-invocable only (disable-model-invocation: true) or also auto-triggered by Claude?
Tools needed: Which tools should the skill have access to? (e.g., Read, Grep, Bash(gh *))
Accepts arguments?: Does the skill need user input via $ARGUMENTS? If so, what's the hint?
Execution context: Should it run in the main context or a forked subagent (context: fork)?

Step 3: Generate the skill

Based on the answers, generate a well-structured SKILL.md file with:

Proper YAML frontmatter including all relevant fields and version: 1.0.0
Clear, actionable instructions in the markdown body
Use of $ARGUMENTS or positional args ($0, $1) if the skill accepts input

Required frontmatter fields:

---
name: <skill-name>
version: 1.0.0
description: <what the skill does and when to use it>
---

Every SKILL.md must include the Apache 2.0 license header immediately after the closing --- of the frontmatter:

<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
or more contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright
ownership. Elasticsearch B.V. licenses this file to you under
the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License.
You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License. -->

Write the skill to skills/<category>/<skill-name>/SKILL.md in the catalog.

Before writing the file, validate skill-name:

Must be kebab-case.
Must start with docs-.
Must not duplicate an existing skill name in skills/**/SKILL.md.

Step 4: Review with the user

After writing the file:

Read it back and present the full content to the user
Ask the user to review it: "Does this look right? Want me to change anything?"
Do NOT move on until the user confirms they're happy with the result
If the user requests changes, edit the file and present the updated version again

Step 5: Generate evals interactively

After the user approves the skill, generate eval test cases as evals/evals.json inside the skill directory. Follow the schema in references/eval-schemas.md.

5a: Draft initial evals

Generate 3-4 evals covering:

Core use case — the happy path the skill is designed for
Edge case — unusual input, boundary condition, or complex scenario
Negative eval — input where the skill should NOT trigger, flag, or produce output. This is critical to prevent false positives and over-triggering. Examples:
- For a linter/checker: valid input that should pass cleanly
- For a generator: a request that falls outside the skill's scope
- For an analyzer: input with nothing to report

Good evals:

Use realistic, substantive prompts (not "do X" — include file paths, context, specifics)
Have expectations that are discriminating (fail when the skill doesn't work, not just pass for any output)
Negative evals should use "Does NOT flag/generate/suggest" expectations
Test the skill's unique value-add, not things the base model already handles

5b: Review with the user

Present the evals and ask: "Here are the test cases I'd suggest — including a negative eval to catch false positives. Do these cover the right scenarios, or do you want to add/change any?"

5c: Iterate

If the user suggests additional scenarios, failure modes, or edge cases, add them. Pay special attention to cases the user has seen in practice — real-world failures make the best evals.

Step 6: Optimize the description (optional)

After evals are written, offer to optimize the skill's description field for better triggering accuracy. The description is the primary mechanism that determines whether Claude invokes a skill.

A good description:

States what the skill does AND specific contexts for when to use it
Is slightly "pushy" to combat under-triggering (Claude tends to not use skills even when they'd help)
Includes trigger words users would naturally say

Step 7: Suggest testing and contributing

Once the user approves, suggest testing:

Running ./install.sh to install it locally
Typing /<skill-name> in Claude Code

Then suggest contributing upstream:

After the skill is created, suggest the following to the user:

Want to share this skill? You can contribute it to the elastic/elastic-docs-skills catalog so other teams can use it too.

I can help you:

Create a branch and commit the new skill

Push it and open a PR against elastic/elastic-docs-skills

Would you like me to do that?

If the user agrees, create a branch named add-skill-<skill-name>, commit the new skill directory, push, and open a PR with:

Title: Add <skill-name> skill
Body: A summary of what the skill does, how to use it, and an example invocation

Guidelines

Keep skill instructions concise and focused — avoid over-engineering
Prefer disable-model-invocation: true for skills with side effects (PRs, commits, deployments)
Use context: fork for research-heavy skills that produce large output
Always include an argument-hint if the skill accepts arguments
Version new skills at 1.0.0 — follow SemVer for updates (MAJOR.MINOR.PATCH)

create-skill

Process