Skip to content

Latest commit

 

History

History
154 lines (112 loc) · 5.33 KB

CONTRIBUTING.md

File metadata and controls

154 lines (112 loc) · 5.33 KB

Contributing to Elastic Docs Skills

Quick start

The fastest way to add a skill is to use the built-in command within this repo:

/create-skill my-new-skill

This walks you through the process interactively and can open a PR for you.

Manual creation

1. Choose a category

Category Purpose Examples
authoring Help write or edit documentation content syntax help, redirects, tagging
review Validate, lint, or check existing content style checks, link validation
workflow Meta-tasks and process automation retros, session analysis

If your skill doesn't fit an existing category, propose a new one in your PR description.

2. Create the skill directory

skills/<category>/<skill-name>/
  SKILL.md

The directory name must be kebab-case and will become the skill's name.

3. Write the SKILL.md

Every skill needs YAML frontmatter followed by markdown instructions.

Required frontmatter

---
name: my-skill
version: 1.0.0
description: One-line description of what the skill does and when to trigger it.
---

Optional frontmatter

argument-hint: <file-or-directory>    # Autocomplete hint (add if skill accepts input)
disable-model-invocation: true        # Only runs via /my-skill, not auto-triggered
context: fork                         # Run in isolated subagent (use for read-only skills)
allowed-tools: Read, Grep, Glob       # Tools available without asking for permission
sources:                              # Upstream URLs this skill encodes
  - https://www.elastic.co/docs/...

Frontmatter guidelines

  • context: fork: Use for skills that only read and report (style checks, validators, retros). Do NOT use for skills that edit files.
  • allowed-tools: List only the tools the skill actually needs. Include Edit or Write only if the skill modifies files.
  • sources: List every upstream documentation URL that the skill's rules are derived from. The weekly freshness checker uses these to detect drift.
  • argument-hint: Add this whenever the skill accepts $ARGUMENTS. Use angle brackets for placeholders: <file-or-directory>.
  • disable-model-invocation: Use for skills that should only run when explicitly invoked via /skill-name, not auto-triggered by Claude's judgment.

Markdown body

The body is the system prompt that drives the skill. Write it as instructions to Claude:

  • Start with "You are a..." role statement
  • Define inputs ($ARGUMENTS)
  • Describe the step-by-step process
  • Include examples and edge cases
  • End with reference URLs (if the skill is derived from upstream docs)

4. Add evals (recommended)

Create evals/evals.json in your skill directory:

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "A realistic user prompt that exercises the skill",
      "expected_output": "Brief description of correct output",
      "expectations": [
        "Specific, testable assertion about the output",
        "Another assertion"
      ]
    }
  ]
}

Eval guidelines

  • Write 3-5 evals covering common use cases and edge cases
  • Each eval needs an id, prompt, and expectations array
  • Expectations should be specific and independently verifiable
  • expected_output is a human-readable summary; expectations are the grading criteria
  • Evals run automatically on PRs that modify skills (via the skill-eval-test workflow)

5. Open a PR

CI will validate:

  • SKILL.md has valid YAML frontmatter with required fields
  • name matches the directory name
  • version is valid SemVer
  • evals.json (if present) has valid structure

Versioning

Follow SemVer when editing existing skills:

  • PATCH (1.0.0 -> 1.0.1): Bug fixes, wording improvements, updated URLs
  • MINOR (1.0.0 -> 1.1.0): New capabilities, additional rules covered
  • MAJOR (1.0.0 -> 2.0.0): Breaking changes to behavior, output format, or interface

Avoiding contradictions

Before writing a new skill, check existing skills for overlapping scope:

  • Read all skills in the same category
  • Search for keywords from your skill's domain across all SKILL.md files
  • If two skills could give conflicting advice, either merge them or clearly delineate their scopes in the descriptions

gh-aw workflows

Agentic workflows live as .md files in .github/workflows/. They are compiled to .lock.yml files via gh aw compile. Rules:

  • Edit the .md file, never the .lock.yml
  • Run gh aw compile .github/workflows/my-workflow.md to regenerate the lock file
  • Commit both the .md and .lock.yml together