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.
2. 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.
3. 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.
4. 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.
5. 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
6. 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/<component-name>.md
• Reusable GLSL patterns/gotchas → .GLSL-Encyclopedia/notes/patterns/<topic>.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.