Creating Skills

Skills are the building blocks of Golden Path. Each skill is a structured instruction set that guides the AI through a multi-step implementation task. This guide walks you through authoring your own skills.

The workflow

Creating a skill follows a plan-then-create workflow:

1. Plan — Call plan_skill with your requirements to get the format guide and a plan template
2. Design — Fill in the plan with phases, arguments, and template references
3. Review — Iterate on the plan with your AI assistant
4. Create — Call create_skill with the structured data to write the skill files

Skill document structure

Every skill is defined as a structured document with YAML frontmatter and a markdown body:

---
name: add-caching
description: Adds Redis caching to a service with cache-aside pattern.
args:
  - name: service_name
    description: Target service name
    required: true
  - name: cache_provider
    description: Cache provider to use
    required: false
    type: string
    enum: [redis, memory]
    default: redis
---

# Add Caching

Adds a caching layer to an existing service using
the cache-aside pattern.

## Prerequisites

- [ ] Target service exists
- [ ] Redis is configured (if using redis provider)

## Execution Steps

### Phase 1: Install packages

Add the caching NuGet packages to the infrastructure
project...

### Phase 2: Create cache service

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

### Phase 3: Register services

Add the cache service to the DI container...

## Success Criteria

- [ ] Solution builds without errors
- [ ] Cache service is registered in DI

Template references

Phases use template references to specify which template file to use and where to write the output:

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

All skill args are automatically replaced as {VarName} placeholders in every template at runtime — no explicit replacement declaration needed.

Template files

Templates are stored alongside the skill definition. They contain source code with variable placeholders:

using Microsoft.Extensions.Caching.Distributed;

namespace {ServiceName}.Infrastructure.Caching;

public class {ServiceName}CacheService
{
    private readonly IDistributedCache _cache;

    public {ServiceName}CacheService(IDistributedCache cache)
    {
        _cache = cache;
    }

    public async Task<T?> GetAsync<T>(string key)
    {
        var data = await _cache.GetStringAsync(key);
        return data is null ? default : JsonSerializer.Deserialize<T>(data);
    }
}

Arguments and variables

Skill arguments map directly to template variables. When the AI calls the skill, argument values replace the corresponding {VariableName} placeholders in templates.

Additional variables come from the architecture configuration:

Standalone vs architecture-bound skills

Skills can exist in two modes:

• Standalone skills — not tied to any architecture. They appear in the Skills section of the sidebar, sorted alphabetically by name. Standalone skills cannot be reordered.
• Architecture-bound skills — belong to a specific architecture. They appear under their architecture in the sidebar and can be reordered via drag-and-drop. The order is persisted and shared with all users who have access to the architecture.

Best practices