Shader Cache Optimization

SKILL.md — shader-cache-optimization Registry Documentation

Skill Identity Card

| Attribute | Value | |-----------|-------| | Name | shader-cache-optimization | | Version | 2.0.0 | | Status | Production Ready | | Domain | Shader Compilation & Cache Performance Engineering | | Type | Agent Harness (Multi-step orchestrator) | | Pattern | Sequential sub-skill delegation with quality gates |

---

Purpose & Scope

This skill provides a structured, evidence-backed analytical workflow for Shader Compilation & Cache Performance Engineering. It transforms Claude into a domain expert that:

1. Gathers authoritative real-time data from GPU vendors, API specifications, and game engines
2. Applies systematic optimization methods for shader compilation stutter
3. Integrates academic research with tier-labeled evidence hierarchy
4. Delivers risk-disclosed outputs with multi-scenario analysis
5. Continuously self-improves via automated knowledge crawl pipeline

---

Skill Registry Schema

Registration

Skills are registered in the skills/ directory with the following contract:

# Frontmatter (required)
name: {skill-name}
description: {trigger description + when to use}
version: {semantic-version}
author: {organization/team}
license: {SPDX identifier}

# Optional metadata
compatibility:
  tools: [list of required tools]
  python: ">=version"
  dependencies: [list with versions]
tags: [list for discoverability]
registry_version: 1.0

Skill Resolution

When a user query matches the description field, the skill is invoked. Resolution priority:

1. Exact name match (/shader-cache-optimization)
2. Description keyword match (contains "shader cache", "stutter", etc.)
3. Domain tag match (shader, vulkan, graphics)
4. Fallback to default (no skill invoked)

Execution Model

┌─────────────────────────────────────────────────────────────┐
│                    USER INPUT                                │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              PRE-FLIGHT: LANGUAGE DETECTION                  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Vietnamese detection: à á ả ã ạ ă â đ è é ê ì í      │  │
│  │ Default: English                                       │  │
│  └──────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    STEP 1: REQUIREMENTS                       │
│  Skill("sub-gather-requirements")                           │
│  → {object, scope, stutter_profile, inputs, constraints}    │
│  ✓ G0: Object confirmed                                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   STEP 2: EVIDENCE COLLECTION                 │
│  Skill("sub-evidence-collector")                            │
│  → {current_data, docs, developments, benchmarks}           │
│  ✓ G1: Data retrieved or limitation flagged                 │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   STEP 3: CORE ANALYSIS                      │
│  Skill("sub-core-analysis")                                 │
│  → {profiling, strategy, config, warmup, scenarios}          │
│  ✓ G2.1-G2.5: Analysis completeness                         │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                STEP 4: KNOWLEDGE UPDATE                       │
│  Skill("sub-knowledge-updater")                             │
│  → {citations, tiers, gaps, coverage}                       │
│  ✓ G3: Academic sources surfaced                            │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  STEP 5: ADVISOR SYNTHESIS                    │
│  Skill("sub-advisor")                                       │
│  → {verdict, scenarios, risks, evidence, actions}            │
│  ✓ G4.1-G4.5: Output completeness                           │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              STEP 6: QUALITY GATE REVIEW                      │
│  Verify U1-U6 + G1-G4 → Auto-fix → Limitation flags         │
│  → Post-Execution Gate Checklist                            │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    FINAL OUTPUT DELIVERY                      │
│  Report with all sections + evidence chain + disclosure      │
└─────────────────────────────────────────────────────────────┘

---

Input/Output JSON Schemas

Input Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ShaderCacheOptimizationInput",
  "type": "object",
  "required": ["query"],
  "properties": {
    "query": {
      "type": "string",
      "description": "User's analysis request in English or Vietnamese",
      "minLength": 10
    },
    "language": {
      "type": "string",
      "enum": ["en", "vi", "auto"],
      "default": "auto",
      "description": "Output language preference (auto-detect if not specified)"
    },
    "analysis_type": {
      "type": "string",
      "enum": ["profile", "strategy", "config", "combined"],
      "default": "combined"
    },
    "constraints": {
      "type": "object",
      "properties": {
        "timeframe": {"type": "string"},
        "budget": {"type": "string"},
        "platform": {"type": "string"}
      }
    },
    "attachments": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Paths to profiling logs, screenshots, or config files"
    }
  }
}

Output Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ShaderCacheOptimizationOutput",
  "type": "object",
  "required": [
    "metadata",
    "executive_summary",
    "inputs_scope",
    "evidence_collected",
    "analysis",
    "action_plan",
    "academic_evidence",
    "disclosure",
    "recommendation",
    "gate_checklist"
  ],
  "properties": {
    "metadata": {
      "type": "object",
      "required": ["date", "analyst", "language", "domain", "version"],
      "properties": {
        "date": {"type": "string", "format": "date-time"},
        "analyst": {"type": "string"},
        "language": {"type": "string", "enum": ["en", "vi"]},
        "domain": {"type": "string"},
        "version": {"type": "string"}
      }
    },
    "executive_summary": {
      "type": "string",
      "minLength": 50
    },
    "inputs_scope": {
      "type": "object",
      "required": ["object", "stutter_profile", "constraints"],
      "properties": {
        "object": {"type": "string"},
        "stutter_profile": {
          "type": "object",
          "properties": {
            "pattern": {"type": "string"},
            "severity": {"type": "string"},
            "triggers": {"type": "array"}
          }
        }
      }
    },
    "evidence_collected": {
      "type": "object",
      "properties": {
        "current_data": {"type": "array"},
        "authoritative_docs": {"type": "array"},
        "recent_developments": {"type": "array"},
        "reference_benchmarks": {"type": "array"}
      }
    },
    "analysis": {
      "type": "object",
      "required": ["profiling", "compile_strategy", "cache_config", "warmup"],
      "properties": {
        "profiling": {"type": "object"},
        "compile_strategy": {"type": "object"},
        "cache_config": {"type": "object"},
        "warmup": {"type": "object"}
      }
    },
    "action_plan": {
      "type": "object",
      "required": ["immediate", "short_term", "long_term"],
      "properties": {
        "immediate": {"type": "array"},
        "short_term": {"type": "array"},
        "long_term": {"type": "array"}
      }
    },
    "academic_evidence": {
      "type": "array",
      "minItems": 3,
      "items": {
        "type": "object",
        "required": ["reference", "tier", "relevance"],
        "properties": {
          "reference": {"type": "string"},
          "tier": {"type": "integer", "minimum": 1, "maximum": 4},
          "relevance": {"type": "number"}
        }
      }
    },
    "disclosure": {
      "type": "string",
      "minLength": 100
    },
    "recommendation": {
      "type": "object",
      "required": ["verdict", "scenarios", "risks", "evidence_chain", "remediation"],
      "properties": {
        "verdict": {
          "type": "string",
          "enum": ["stutter_free", "conditional", "persistent_stutter", "inconclusive"]
        },
        "scenarios": {"type": "object"},
        "risks": {"type": "array", "minItems": 3},
        "evidence_chain": {"type": "object"},
        "remediation": {"type": "array"}
      }
    },
    "gate_checklist": {
      "type": "object",
      "required": ["universal_gates", "domain_gates", "limitations"],
      "properties": {
        "universal_gates": {"type": "object"},
        "domain_gates": {"type": "object"},
        "limitations": {"type": "array"}
      }
    }
  }
}

---

Sub-Skill Registry

Available Sub-Skills

| Sub-Skill | Step | Purpose | Input | Output | |-----------|------|---------|-------|--------| | sub-gather-requirements | 1 | Intake & clarification | User query | Structured requirements object | | sub-evidence-collector | 2 | Data fetching | Requirements | Evidence bundle with sources | | sub-core-analysis | 3 | Domain analysis | Game/engine/GPU data | Optimization strategy | | sub-knowledge-updater | 4 | Academic lookup | Topic keywords | Tier-labeled citations | | sub-advisor | 5 | Synthesis & recommendation | All prior analysis | Risk-disclosed conclusion |

Sub-Skill Registration Format

Each sub-skill file must include:

---
name: sub-{skill-name}
description: {one-line trigger description}
version: 1.0.0
---

## Role & Persona
## Workflow (Harness Flow)
## Tools
## Output Format
## Quality Gates

---

Quality Gate Registry

Universal Gates (U1-U6)

| Gate ID | Name | Check | Auto-Fix | Retry Limit | |---------|------|-------|----------|------------| | U1 | Source Completeness | ≥3 sources, ≥1 Tier 1-2 | Fetch from KB | 2 | | U2 | Disclosure | Present before recommendation | Prepend template | 2 | | U3 | Evidence Hierarchy | Tier labels per source | Annotate sources | 2 | | U4 | Language Consistency | Matches user preference | Translate output | 1 | | U5 | Template Completeness | All sections present | Add missing sections | 2 | | U6 | Claim Traceability | Each claim cited or flagged | Mark unsupported claims | 2 |

Domain Gates (G1-G4)

| Gate ID | Name | Check | Auto-Fix | Retry Limit | |---------|------|-------|----------|------------| | G1 | Profiling Completeness | Severity quantified | Use benchmarks | 2 | | G2 | Compilation Strategy | Async/pre-build applied | Select from matrix | 2 | | G3 | Cache Configuration | Persistence configured | Platform-specific | 2 | | G4 | Warm-up Strategy | First-play addressed | Budget recommendation | 2 |

---

Tool Definitions

Required Tools

| Tool | Purpose | Usage Frequency | |------|---------|-----------------| | WebSearch | Live data retrieval | Per analysis | | WebFetch | Documentation scraping | Per analysis | | Read | Knowledge base access | Per step | | Write | Knowledge updates | During crawl | | Bash | Crawl pipeline execution | Scheduled | | Skill | Sub-skill delegation | Sequential |

Tool Usage Patterns

WebSearch:

# Domain-specific searches with recency filter
queries = [
    f"{game} shader cache stutter fix",
    f"{gpu_vendor} driver cache optimization",
    f"{api_version} pipeline cache best practices"
]

WebFetch:

# Authoritative documentation sources
sources = [
    "https://docs.nvidia.com/gameworks/technologies/",
    "https://registry.khronos.org/vulkan/specs/",
    "https://docs.unrealengine.com/5.0/en-US/optimizing-shaders/"
]

---

Hooks System

Lifecycle Hooks

| Hook | Timing | Purpose | Signature | |------|--------|---------|-----------| | on_pre_flight | Before Step 1 | Language detection, validation | on_pre_fly(query: str) -> LangResult | | on_step_start | Before each step | Logging, state sync | on_step_start(step_id: int, context: dict) | | on_step_complete | After each step | Gate validation, state update | on_step_complete(step_id: int, result: dict) | | on_gate_failure | On gate check failure | Auto-fix, limitation flagging | on_gate_failure(gate_id: str, retry: int) | | on_output_ready | Before final delivery | Template formatting, verification | on_output_ready(report: dict) -> dict | | on_error | On any error | Graceful degradation, logging | on_error(error: Exception, context: dict) |

Hook Implementation

Hooks are defined in config/hooks.yaml:

pre_flight:
  handler: "shader_cache_optimization.hooks:pre_flight_detection"
  enabled: true

step_start:
  handler: "shader_cache_optimization.hooks:log_step_start"
  enabled: true
  log_level: "INFO"

gate_failure:
  handler: "shader_cache_optimization.hooks:handle_gate_failure"
  enabled: true
  max_retries: 2
  fallback_strategy: "limitation"

---

Configuration Management

Config Structure

config/
├── default.yaml          # Base configuration
├── production.yaml       # Production overrides
├── development.yaml      # Development overrides
└── hooks.yaml           # Hook definitions and handlers

Configuration Schema

# default.yaml
skill:
  name: "shader-cache-optimization"
  version: "2.0.0"
  
quality:
  gates:
    universal: ["U1", "U2", "U3", "U4", "U5", "U6"]
    domain: ["G1", "G2", "G3", "G4"]
  retry_limit: 2
  strict_mode: false

knowledge:
  base_path: "SECOND-KNOWLEDGE-BRAIN.md"
  crawl_schedule:
    academic: "0 8 * * 1"
    news: "0 7 * * *"
  
sources:
  tier_1:
    - IEEE Transactions on Visualization and Computer Graphics
    - ACM Transactions on Graphics
  tier_2:
    - Khronos Group Specifications
    - GPU Vendor Documentation
  
degradation:
  levels:
    - level: 0
      banner: null
    - level: 1
      banner: "LIMITATION NOTICE Level 1"
    - level: 2
      banner: "LIMITATION NOTICE Level 2"
    - level: 3
      banner: "LIMITATION NOTICE Level 3"
    - level: 4
      banner: "LIMITATION NOTICE Level 4"
      terminate: true

---

Validation & Testing

Skill Validation

Skills are validated against the 8-File Contract:

python tools/validate_project.py

Checks:

• ✓ All required files present
• ✓ Frontmatter complete and valid
• ✓ Sub-skills properly structured
• ✓ Quality gates defined
• ✓ Knowledge base seeded
• ✓ Tools documented

Integration Testing

# Run all test scenarios
python tools/run_test_scenarios.py --all

# Run specific scenario
python tools/run_test_scenarios.py --scenario 1

# Dry-run knowledge crawl
python tools/knowledge_updater.py --dry-run

---

Performance Optimization

Context Window Management

• Token budgeting: Each sub-skill has a token allocatio

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/shader-cache-optimization-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.