Skill Format

Every Golden Path skill is defined as a structured document with YAML frontmatter and a markdown body. Skills are stored in the database and rendered to markdown when executed. This page is the complete specification for the format.

Frontmatter

The frontmatter defines the skill's metadata and argument schema. It is parsed as YAML between --- delimiters.

Name
name
Type
string
Description
Skill slug, used as the MCP tool name. Must be kebab-case (e.g., add-caching).
Name
description
Type
string
Description
What the skill does, in 1-2 sentences. Shown when listing available tools.
Name
tool_name
Type
string
Description
Optional override for the MCP tool name. Defaults to name.
Name
args
Type
array
Description
Skill arguments. Each becomes a parameter on the MCP tool.

Argument fields

Each entry in args accepts:

Name
name
Type
string
Description
Argument name (snake_case). Also used as the template variable name (PascalCase conversion automatic).
Name
description
Type
string
Description
What this argument is for. Shown in tool parameter descriptions.
Name
required
Type
boolean
Description
Whether the argument must be provided.
Name
type
Type
string
Description
Value type: string (default), boolean, number.
Name
enum
Type
array
Description
Allowed values. Renders as a dropdown/choice in the tool schema.
Name
default
Type
string
Description
Default value when not provided.

Example frontmatter

---
name: add-caching
description: Adds Redis caching to a service with cache-aside pattern.
args:
  - name: service_name
    description: Name of the target service (PascalCase)
    required: true
  - name: cache_provider
    description: Cache backend to use
    required: false
    type: string
    enum: [redis, memory]
    default: redis
  - name: ttl_minutes
    description: Default cache TTL in minutes
    required: false
    type: number
    default: "30"
---

Body structure

The markdown body follows a standard structure with named sections:

Title

The H1 heading. Describes the skill's purpose.

# Add Caching

Description (optional)

Free text between the title and first section. Provides context.

Prerequisites

A checklist of conditions that should be true before executing:

## Prerequisites

- [ ] Target service exists and builds
- [ ] Redis server is accessible (if using redis provider)

Execution Steps

The phases of the skill, each as an H3 under the execution steps section:

## Execution Steps

### Phase 1: Install packages

Add NuGet packages to the infrastructure project:
- `Microsoft.Extensions.Caching.StackExchangeRedis`

### Phase 2: Create cache service

**Template:** `CacheService.cs`
**Target:** `src/{ServiceName}/Infrastructure/Caching/{ServiceName}CacheService.cs`

Create the cache service implementation.

### Phase 3: Register in DI

Add the following to the DI registration...

Success Criteria

A checklist for validating the result:

## Success Criteria

- [ ] Solution builds without errors
- [ ] Cache service resolves from DI container
- [ ] GET endpoint returns cached response on second call

Template references

Phases reference template files using bold-label patterns:

Name
Template
Type
reference
Description
Filename of the template in the skill directory.
Name
Target
Type
path
Description
Output path with variable placeholders.
Name
Condition
Type
string
Description
Optional condition — template-ref is only included when a skill arg matches the specified value (e.g. EndpointStyle=controller).

All skill args are automatically available as {VarName} placeholders in templates — no need to declare replacements explicitly.

Template reference

**Template:** `CacheService.cs`
**Target:** `src/{ServiceName}/Infrastructure/Caching/{ServiceName}CacheService.cs`

Sections ordering

By default, sections appear in this order: Prerequisites, Execution Steps (phases), Success Criteria.

You can customize the ordering with the sections parameter in create_skill, inserting free-form sections at any position:

Custom section ordering

[
  { "type": "prerequisites", "heading": "Prerequisites", "content": "..." },
  { "type": "free", "heading": "Architecture Notes", "content": "..." },
  { "type": "execution-steps", "heading": "Execution Steps", "content": "" },
  { "type": "success-criteria", "heading": "Success Criteria", "content": "..." }
]