oh-my-posh/.agents/skills/segment-create/SKILL.md

name, description

name	description
segment-create	Full scaffolding workflow for creating a new Oh My Posh segment. Invoke when asked to add a new segment: generates the Go source, registers the type, creates documentation, updates the sidebar and JSON schema.

Segment scaffolding instructions

Goal

• Given user inputs (segment id, Go type name, title, category, description, properties, template), generate all required code and docs to add a new segment end-to-end, following repo conventions.

Inputs

• id: kebab/slug used as type and docs filename (e.g., new)
• goType: PascalCase name for the Go struct (e.g., New)
• title: human readable (e.g., New)
• category: one of cli|cloud|health|languages|music|scm|system|web
• description: one-line description
• properties: list of { key, type, title, description, default }
• template: default template string (e.g., {{.Text}})

Contract

• Idempotent: do not duplicate registrations, constants, map entries, sidebar links, or schema entries.
• Alphabetical insertions where applicable.
• Compile-ready Go code, formatted.
• Docs lint clean according to the markdown skill (.github/skills/markdown/SKILL.md).

Implementation steps

1. Create Go writer file: src/segments/<id>.go

• If file exists, skip creation.
• Use this template; include property consts for each property key.

package segments

import (
    "github.com/jandedobbeleer/oh-my-posh/src/segments/options"
    "github.com/jandedobbeleer/oh-my-posh/src/runtime"
)

type {{goType}} struct {
    Base

    // computed fields used in template
    Text string
}

// properties
const (
{{#each properties}}
    // {{this.title}}: {{this.description}}
    {{ pascalCase this.key }} options.Property = "{{this.key}}"
{{/each}})

func (s *{{goType}}) Enabled() bool {
    // set up data for the template, using defaults from properties
    {{#if (propExists properties "text")}}
    s.Text = s.props.GetString({{ pascalCase "text" }}, {{ defaultFor "text" }})
    {{else}}
    s.Text = s.props.GetString({{ pascalCase (firstKey properties) }}, "")
    {{/if}}
    return true
}

func (s *{{goType}}) Template() string {
    return {{ printf "%q" template }}
}

1. Register in src/config/segment_types.go

• Ensure in init() there is gob.Register(&segments.{{goType}}{}) exactly once.
• Add constant: {{ upper id }} SegmentType = "{{id}}" in the alphabetical block.
• Add to var Segments = map[SegmentType]func() SegmentWriter{} with key {{ upper id }} mapping to &segments.{{goType}}{}.
• Keep lists alphabetically sorted. If not sorted, insert at correct position.

1. Documentation file

• Consult the segment-docs skill (.github/skills/segment-docs/SKILL.md) for the Go-to-documentation type mapping and rules for extracting options and template properties.
• Path: website/docs/segments/{{category}}/{{id}}.mdx.
• If file exists, skip. Else create with this template:

---
id: {{id}}
title: {{title}}
sidebar_label: {{title}}
---

## What

{{description}}

## Sample Configuration

import Config from '@site/src/components/Config.js';

<Config data={{
  "type": "{{id}}",
  "style": "powerline",
  "powerline_symbol": "\uE0B0",
  "foreground": "#193549",
  "background": "#ffeb3b",
  "options": {
{{#each option}}
    "{{this.key}}": {{ json this.default }},
{{/each}}
  }
}}/>

## Options

| Name | Type | Description | Default |
| ---- | ---- | ----------- | ------- |
{{#each option}}| `{{this.key}}` | `{{this.type}}` | {{this.description}} | `{{ stringify this.default }}` |
{{/each}}

1. Sidebar

• Update website/sidebars.js under the correct category array to include "segments/{{category}}/{{id}}".
• Insert alphabetically; if already present, do nothing.

1. JSON Schema

• File: themes/schema.json.
• Add "{{id}}" to #/definitions/segment/properties/type/enum if missing.
• Add an allOf entry for this segment guarded by { properties: { type: { const: "{{id}}" } } } that declares each property as defined by inputs. Use appropriate JSON Schema types and include title, description, default.
• Keep the allOf array in a stable order by type name if feasible; otherwise append if not present.

Validation

• After changes, run go build (task: build oh-my-posh). Ensure no compile errors.
• Check markdown formatting; respect 120-char line length and fenced blocks with language.

Notes

• Use UTF-32 escapes (e.g., "\uEFF1") for icon defaults in docs and code.
• Keep code minimal. Complex logic should be added by maintainers after scaffold if needed.

Optional

1. Tests

• Create a minimal test file at src/segments/{{id}}_test.go using the table-driven style. Include at least a happy-path test that asserts Enabled() returns true and the template renders expected output with default options.