GLSL Encyclopedia

Overview

Use a docs-first workflow for GLSL work. Prefer the official GLSL language/specification docs at https://docs.vulkan.org/glsl/latest/index.html, consult cached local copies under .GLSL-Encyclopedia/ before re-fetching, and record useful authoritative excerpts plus environment-specific operational learnings so future work gets faster, safer, and more grounded.

This skill is for the GLSL language/spec layer. It should trigger for real GLSL syntax/semantic/interface questions, not for generic rendering talk and not for Vulkan API questions unless the actual issue is specifically about GLSL shader source.

Workflow

1. Classify the task
• Decide whether the task is a GLSL language question, shader-authoring task, shader-review task, compiler-error/debugging task, stage-specific behavior question, or cross-language translation/comparison task where GLSL is one side.
• Use this skill when the task materially depends on GLSL syntax, qualifiers, types, built-ins, interface/layout rules, stage rules, preprocessor/version behavior, or shader authoring semantics.
• Do not use this skill for generic rendering concepts, generic Vulkan API debugging, or non-GLSL shader languages unless the GLSL language layer is actually in play.

1. Check local cache first
• Use .GLSL-Encyclopedia/ as the local knowledge/cache root.
• Check these locations first when relevant:
• .GLSL-Encyclopedia/docs/docs.vulkan.org/glsl/latest/...
• .GLSL-Encyclopedia/notes/components/...
• .GLSL-Encyclopedia/notes/patterns/...
• .GLSL-Encyclopedia/inventory/...
• If a cached page or note already answers the question well enough, use it.

1. Consult authoritative GLSL docs before answering or acting
• Before answering direct or indirect GLSL questions that depend on exact syntax, qualifier behavior, type rules, stage restrictions, built-in variable/function semantics, layout/interface rules, or version-sensitive details, consult the official GLSL docs unless the answer is already well-supported by the local cache.
• Before performing non-trivial GLSL shader review or authoring guidance, consult the relevant docs first when:
• exact language syntax or legal combinations matter
• stage-specific behavior or interface matching is easy to misremember
• the task involves compile errors, layout rules, extension/version behavior, or built-in semantics
• If the problem is really about Vulkan API object behavior, synchronization, descriptors, swapchains, or VUID-driven valid-usage rules rather than GLSL language semantics, prefer the Vulkan skill instead of stretching this one.
• Do not improvise fragile GLSL answers from memory when the docs are easy to check.

1. Cache consulted docs locally
• When you consult a GLSL docs page, save a normalized cache copy under .GLSL-Encyclopedia/docs/docs.vulkan.org/glsl/latest/....
• Mirror the official docs path structure as much as practical.
• Cache only pages actually consulted; do not try to mirror the whole GLSL spec eagerly.
• Use scripts/cache_doc.py when appropriate.

1. Separate authoritative documentation from local observations
• Store official-doc-derived material under .GLSL-Encyclopedia/docs/....
• Store environment-specific operational knowledge under:
• .GLSL-Encyclopedia/notes/components/
• .GLSL-Encyclopedia/notes/patterns/
• .GLSL-Encyclopedia/inventory/
• Distinguish clearly between:
• authoritative documented behavior
• observed project/environment shader conventions
• inferred best-practice guidance

1. Record useful local learnings
• After useful live work, save durable notes such as:
• project-specific shader conventions
• recurring compile/validation-error patterns
• stage-interface or layout gotchas
• version/extension adoption decisions
• safe/unsafe operational boundaries for the codebase or environment
• Prefer concise durable notes over re-learning the same GLSL details later.

Live Work Rules

• Treat authoritative GLSL docs lookup as the default preflight for non-trivial GLSL work.
• Prefer read/inspect first when entering unfamiliar shader code.
• Treat stage interfaces, layout qualifiers, buffer/image/sampler usage, preprocessor/version behavior, built-in semantics, and compiler-error interpretation as higher-sensitivity areas.
• When uncertainty remains after checking cache + docs, say so and avoid bluffing.
• When answering a question, mention when useful whether the answer comes from cached official docs, a fresh official docs lookup, or live observed shader/project state.

Data Root

Use this workspace-local root for cache and notes:

• .GLSL-Encyclopedia/

Expected structure:

• .GLSL-Encyclopedia/docs/docs.vulkan.org/glsl/latest/...
• .GLSL-Encyclopedia/notes/components/...
• .GLSL-Encyclopedia/notes/patterns/...
• .GLSL-Encyclopedia/inventory/...

Use scripts/init_workspace.py to create or repair the expected directory structure.

Note Destinations

• Component-specific observations → .GLSL-Encyclopedia/notes/components/.md
• Reusable GLSL patterns/gotchas → .GLSL-Encyclopedia/notes/patterns/.md
• Environment-wide shader/access info → .GLSL-Encyclopedia/inventory/*.md
• Cached official docs → .GLSL-Encyclopedia/docs/docs.vulkan.org/glsl/latest/...

Secrets / Sensitive Data

• Do not store plaintext credentials, API keys, session tokens, private URLs, recovery codes, or other secrets in the encyclopedia notes/inventory tree.
• If a note needs to mention access details, keep it high-level and redact or omit secret material.
• Treat these workspace notes as operational memory, not as a secrets vault.

Resources

• scripts/init_workspace.py — create or repair the .GLSL-Encyclopedia/ directory tree.
• scripts/cache_doc.py — fetch and cache a consulted official GLSL docs page under .GLSL-Encyclopedia/docs/....
• references/workflow.md — detailed operating workflow and evidence-handling rules.
• references/cache-layout.md — canonical .GLSL-Encyclopedia/ directory structure.
• references/topic-map.md — useful GLSL topic groupings for faster authoritative lookup.

Good Outcomes

• Answer a GLSL question using cached or freshly checked official docs instead of guesswork.
• Inspect GLSL shader code after checking the relevant docs and record any new project-specific language or convention knowledge.
• Build a growing local GLSL knowledge cache that makes later work faster, safer, and more grounded.
• Turn one-off GLSL discoveries into durable notes so future work does not rediscover them from scratch.

Avoid

• Answering GLSL-specific questions purely from memory when the docs are easy to consult.
• Treating local project shader conventions as if they were guaranteed authoritative GLSL behavior.
• Dumping large amounts of low-value docs into the workspace without a reason.
• Writing project-specific observations into the official-doc cache tree.
• Confusing generic Vulkan API questions with GLSL language questions when the actual issue is not about GLSL itself.