create-skill

Category: Tools & Productivity | Uploader: elastic | Downloads: 0 | Version: v1.0（Latest）
Interactively create a new Claude Code skill and add it to the elastic-docs-skills catalog. Use when the user wants to generate a new skill, scaffold a slash command, or build automation for docs tasks.
Changelog: Source: GitHub https://github.com/elastic/elastic-docs-skills
Directory Structure

Current level: tree/main/.claude/skills/create-skill/
📁 agents/
- 📄 analyzer.md 2.2 KB
- 📄 comparator.md 1.7 KB
- 📄 grader.md 2.1 KB
📁 references/
- 📄 eval-schemas.md 2.2 KB
📄 SKILL.md 8.3 KB
SKILL.md

---
name: create-skill
version: 1.0.0
description: Interactively create a new Claude Code skill and add it to the elastic-docs-skills catalog. Use when the user wants to generate a new skill, scaffold a slash command, or build automation for docs tasks.
disable-model-invocation: true
argument-hint: [skill-name (optional)]
allowed-tools: Read, Write, Bash(mkdir *), Bash(ls *), Bash(git *), Bash(gh *), Glob, Grep, AskUserQuestion
---
<!-- 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. -->

You are a skill generator for the [elastic/elastic-docs-skills](https://github.com/elastic/elastic-docs-skills) catalog. Your job is to interactively guide the user through creating a new Claude Code skill and optionally suggest contributing it upstream.

## Process

### 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):

1. **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.
2. **Category**: Which category does this skill belong to? (e.g., `authoring`, `review`, `workflow`, `testing`)
3. **Trigger**: Should it be user-invocable only (`disable-model-invocation: true`) or also auto-triggered by Claude?
4. **Tools needed**: Which tools should the skill have access to? (e.g., `Read, Grep, Bash(gh *)`)
5. **Accepts arguments?**: Does the skill need user input via `$ARGUMENTS`? If so, what's the hint?
6. **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:
```yaml
---
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:

```html
<!-- 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:

1. Read it back and present the full content to the user
2. Ask the user to review it: **"Does this look right? Want me to change anything?"**
3. Do NOT move on until the user confirms they're happy with the result
4. 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:

1. **Core use case** — the happy path the skill is designed for
2. **Edge case** — unusual input, boundary condition, or complex scenario
3. **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](https://github.com/elastic/elastic-docs-skills) catalog so other teams can use it too.
>
> I can help you:
> 1. Create a branch and commit the new skill
> 2. 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)
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...
create-skill

Directory Structure

SKILL.md

Report

Notice
