# Shader Cache Optimization

> Shader Cache Optimization to Eliminate Game Stuttering — Shader Compilation & Cache Performance Engineering evidence-backed analysis harness. Use this skill when analyzing shader compilation stutter, optimizing cache strategies, configuring driver/DXVK settings, or needing evidence-backed recommendations for game performance issues. Triggers on: shader cache, stuttering, frametime spikes, Vulkan/…

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-shader-cache-optimization-agent-skill-shader-cache-optimization-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/shader-cache-optimization-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-shader-cache-optimization-agent-skill-shader-cache-optimization-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```yaml
# 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

```json
{
  "$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

```json
{
  "$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:

```markdown
---
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:**
```python
# 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:**
```python
# 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`:

```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

```yaml
# 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:

```bash
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

```bash
# 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](https://github.com/dungnotnull)
- **Source:** [dungnotnull/shader-cache-optimization-agent-skill](https://github.com/dungnotnull/shader-cache-optimization-agent-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-shader-cache-optimization-agent-skill-shader-cache-optimization-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.