Golden Blueprint

The canonical template for building production-grade skill agents. 15 components that ensure your skills are robust, maintainable, and ready for autonomous operation.

Skill Anatomy

Every CatalystRL skill follows a standard directory structure:

skill-name/

skill-name/
├── SKILL.md              # Main prompt (the skill definition)
├── config.json           # Configuration and settings
├── rules.json            # Validation rules
├── scripts/              # Deterministic scripts
│   ├── README.md
│   ├── validate-input.sh
│   └── check-preconditions.sh
├── hooks/                # Optional lifecycle hooks
└── references/           # Optional reference materials

The Three Tiers

Skills are classified by their Deterministic Quotient (DQ) - the ratio of scripted operations to total operations.

Tier 1

DQ: 60-90%

All 15 components required. Highly automated, minimal LLM decisions.

Examples: commit, arch-validator

Tier 2

DQ: 30-60%

Components 1-8, 11-12 required. Balanced automation and reasoning.

Examples: bootstrap, remember

Tier 3

DQ: 10-30%

Components 1-8, 12 required. Primarily reasoning-based.

Examples: agent-builder, executive

15 Components

#	Component	Config	Required
01	ABES Integration	abes_config	Yes
02	Trust Awareness	trust_config	Yes
03	Evolution Readiness	evolution_config	Tier 1
04	Gate Integration	gate_config	Yes
05	Memory Configuration	memory_context	Yes
06	Structure Standard	(file layout)	Yes
07	Telemetry Schema	telemetry	Yes
08	Testing Requirements	testing	Tier 1
09	Scripts Layer	scripts	Tier 1
10	Inter-Skill Protocol	(patterns)	Optional
11	State Patterns	state_paths	Tier 1-2
12	Offline First	offline_config	Yes
13	Validation Rules	rules.json	Recommended
14	Skill Evaluation	eval_config	Tier 1
15	Context Handoff	context_handoff	Recommended

Creating a New Skill

Step 1: Create the directory

mkdir -p ~/.claude/skills/my-skill/scripts
cd ~/.claude/skills/my-skill

Step 2: Create SKILL.md

The prompt file defines what your skill does:

SKILL.md

---
name: my-skill
description: >
  Brief description of what this skill does.
  Use when user says "do something specific".
invocation: user
user-invocable: true
---

# My Skill

## Overview
What this skill accomplishes.

## Steps

### Step 1: Validate Input
Check that inputs are valid before proceeding.

### Step 2: Execute Operation
Perform the main operation.

### Step 3: Generate Report
Output results to the user.

Step 3: Create config.json

config.json

{
  "agent": {
    "id": "my_skill_001",
    "name": "My Skill",
    "type": "Specialized",
    "blueprint": "Step-Graph Skill"
  },
  "memory_context": {
    "cross_cutting": false,
    "repos": ["detect"]
  },
  "trust_config": {
    "initial_level": "MEDIUM",
    "capabilities": {
      "MEDIUM": ["read", "analyze"],
      "HIGH": ["read", "analyze", "write"]
    }
  },
  "offline_config": {
    "enabled": true,
    "fallback_behavior": "local_only"
  }
}

Step 4: Validate compliance

# Run the compliance validator
./golden-blueprint/validate-golden-compliance.sh my-skill

Key Concepts

Step-Graph Architecture

Skills define steps with requires and provides arrays, forming a directed acyclic graph (DAG). This enables dependency validation and parallel execution where possible.

Scripts Layer

Deterministic operations (validation, file checks, calculations) go in bash/Python scripts. This reduces token usage and improves reliability. The skill prompt calls these scripts rather than implementing logic inline.

Gate Integration

Gates enforce safety at critical points. A gate can block operations, require approval, or escalate to human review. Failed gates create bounties for resolution.

Offline First

All skills must work without network access. Platform features (telemetry, bounties, trust updates) gracefully degrade when offline, queuing operations for later sync.

Full Blueprint Documentation

The complete Golden Blueprint with all 15 component specifications will be available when the repository goes public.

View repository progress →