name: new-skill
description: Create a new custom skill with best practices
prompt: |
  Help the user create a new Anteroom skill YAML file.

  Ask what the skill should do, then generate a well-structured skill file
  following these best practices:

  ## Skill YAML Format

  ```yaml
  name: skill-name
  description: One-line description shown in /skills list
  prompt: |
    Multi-line prompt template for the AI.
  ```

  ## Rules

  - **name**: lowercase alphanumeric with hyphens/underscores only (`[a-z0-9][a-z0-9_-]*`)
  - **description**: concise, shown in `/skills` list. Keep under 80 characters
  - **prompt**: use YAML block scalar `|` for multi-line. This is required
  - **Do NOT use `content:` for the prompt field** — local CLI skills require `prompt:`.
    The `content:` field is only used by pack artifacts and will cause a "missing 'prompt' field" error.
  - **Backslash safety**: YAML double-quoted strings treat backslashes as escape characters
    (`\s` → error, `\d` → error). ALWAYS use the block scalar `prompt: |` for prompts
    containing regex, backslash sequences, colons, or curly braces.
  - Use `{args}` as a placeholder where user arguments should be inserted inline
  - If `{args}` is absent, arguments are appended as `Additional context: <args>`

  ## Design Guidelines

  1. **Be specific**: tell the AI exactly what steps to follow, what tools to use,
     and what output format to produce
  2. **Be structured**: use numbered steps for workflows, bullet points for checklists
  3. **Set constraints**: specify what NOT to do if the AI might over-engineer
  4. **Include verification**: end with a validation step (run tests, check output)
  5. **Keep prompts focused**: one skill = one workflow. Don't combine unrelated tasks
  6. **Use block scalar**: always use `prompt: |` to avoid YAML parsing issues with
     colons, curly braces, or special characters in the prompt text

  ## Common Patterns

  ### Tool-using workflow
  ```yaml
  prompt: |
    1. Read the relevant files with read_file
    2. Make the changes
    3. Run tests to verify
  ```

  ### Template with arguments
  ```yaml
  prompt: |
    Analyze the code in {args} and suggest improvements.
    Focus on readability, performance, and error handling.
  ```

  ### Guard rails
  ```yaml
  prompt: |
    Review the git diff for security issues.
    Do NOT make changes. Only report findings.
    Format: file:line — severity — description — fix
  ```

  ## Workflow

  The user's skill request: {args}

  1. If no skill request was provided above, ask the user what the skill should do.
     Otherwise, use the provided description directly — do NOT re-ask.
  2. Determine the best skill name (kebab-case, descriptive)
  3. Write a clear description
  4. Design the prompt with specific steps
  5. Determine the save location:
     - Project-specific: `.anteroom/skills/` or `.claude/skills/`
     - Global (all projects): `~/.anteroom/skills/`
  6. Write the YAML file to disk. IMPORTANT: use `.yaml` extension (not `.yml`)
  7. After writing, read the file back and parse it as YAML. Confirm:
     (a) it is valid YAML (no parse errors),
     (b) the top-level mapping contains a `prompt` key (not `content`), and
     (c) the `prompt` value is a non-empty string.
     If any check fails, fix the file and re-validate.
  8. Tell the user to run `/skills` to see it in the list (shows searched directories)
  9. Mention: "Skills are one of 7 artifact types in Anteroom (alongside rules,
     instructions, context, memory, MCP servers, and config overlays). To share
     this skill with your team, bundle it into a pack with `/new-pack`."
