[add] skills for authoring docs & tutorials

Author: vmarcella

.codex/environments/environment.toml

@@ -0,0 +1,6 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "lambda-rs"
+
+[setup]
+script = "./scripts/setup.sh"

.codex/skills/long-lived-docs-authoring/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: long-lived-docs-authoring
+description: Use when drafting or revising long-lived repository documentation such as specs, roadmaps, guides, feature docs, or planning docs that need Lambda's required metadata, structure, and documentation style. Do not use for tutorials; use `tutorial-authoring` instead.
+---
+
+# Long Lived Docs Authoring
+
+Use this skill for durable Markdown documents that are meant to stay in the
+repository and be maintained over time. The goal is to apply Lambda's
+documentation metadata, tone, and maintenance rules without keeping those
+details in the main task prompt.
+
+## When To Use
+
+- New or updated specifications in `docs/specs/`.
+- Roadmaps, plans, feature documents, and other durable docs in `docs/`.
+- Documentation changes that need YAML front matter, changelog discipline,
+  and repository-specific style constraints.
+- Do not use this skill for tutorials in `docs/tutorials/`.
+- Do not use this skill for Rustdoc-only work.
+
+## Workflow
+
+1. Identify the document type and location.
+   Use `docs/specs/_spec-template.md` for new specifications instead of
+   starting from another spec.
+2. Add or preserve the metadata header.
+   Long-lived docs require YAML front matter with these fields:
+   `title`, `document_id`, `status`, `created`, `last_updated`, `version`,
+   `engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
+   `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
+3. Structure the document for maintenance.
+   Keep sections short, scannable, and diff-friendly. Specifications should
+   include a table of contents. Use stable headings and avoid unnecessary
+   renames.
+4. Apply repository documentation style.
+   Use clear, direct, neutral language in active voice. Prefer present tense.
+   Avoid conversational phrasing, rhetorical questions, marketing language,
+   speculation, emojis, exclamation-based emphasis, and AI authorship
+   references.
+5. Use consistent technical terminology.
+   Define acronyms on first use in each document. Prefer American English.
+   Refer to crates by name, such as `lambda-rs` and `lambda-rs-platform`.
+   Wrap code identifiers in backticks.
+6. Keep examples minimal and buildable.
+   Use concise Rust sketches when proposing APIs. Mirror the repository's
+   existing builder and command patterns. Use ASCII diagrams only and do not
+   embed binaries.
+7. Update maintenance metadata on substantive edits.
+   Update `last_updated`, bump `version` semantically, set `repo_commit` to
+   `HEAD`, and append or update the `Changelog` section.
+
+## Required Style Rules
+
+- Use RFC-2119 keywords when the content is normative.
+- Prefer `Rationale` bullets instead of long "Why" paragraphs.
+- Keep bullets short when possible.
+- Avoid filler sentences and meta commentary such as "this aims to".
+- Do not make unscoped promises such as "we will add" without a linked issue.
+
+## Validation Checklist
+
+- Metadata header is present and complete.
+- The file uses stable headings and short sections.
+- The tone is professional, direct, and repository-aligned.
+- Acronyms are defined on first use.
+- Code snippets are minimal and stylistically consistent with the repository.
+- `last_updated`, `version`, `repo_commit`, and `Changelog` are updated for
+  substantive edits.

.codex/skills/long-lived-docs-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Long-Lived Docs"
+  short_description: "Author specs, guides, and durable docs"
+  default_prompt: "Use $long-lived-docs-authoring to draft or revise a spec, roadmap, or guide for this repository."

.codex/skills/tutorial-authoring/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: tutorial-authoring
+description: Use when creating or revising step-by-step tutorials in `docs/tutorials/`. This skill applies Lambda's required metadata, instructional structure, tone, code-snippet rules, and validation expectations for tutorial documents.
+---
+
+# Tutorial Authoring
+
+Use this skill for tutorial documents that teach a discrete task in the
+repository. It includes the long-lived documentation rules that tutorials
+inherit, plus the additional section and narrative requirements specific to
+`docs/tutorials/`.
+
+## When To Use
+
+- New tutorials in `docs/tutorials/`.
+- Revisions to existing tutorials that change structure, examples, or prose.
+- Documentation tasks that teach a step-by-step workflow with validation and
+  exercises.
+- Do not use this skill for generic guides, specs, or roadmaps outside
+  `docs/tutorials/`.
+
+## Workflow
+
+1. Place the file correctly.
+   Tutorials belong in `docs/tutorials/` and should use kebab-case file names.
+   Include the `tutorial` tag in the metadata.
+2. Add the required metadata header.
+   Tutorials use the same YAML front matter fields as other long-lived docs:
+   `title`, `document_id`, `status`, `created`, `last_updated`, `version`,
+   `engine_workspace_version`, `wgpu_version`, `shader_backend_default`,
+   `winit_version`, `repo_commit`, `owners`, `reviewers`, and `tags`.
+3. Build the required section layout.
+   Tutorials should include a table of contents and these sections:
+   `Goals`, `Overview`, `Prerequisites`, `Implementation Steps`,
+   `Validation`, `Notes`, `Conclusion`, `Exercises`, and `Changelog`.
+4. Write each implementation step as instruction plus outcome.
+   Explain intent and rationale before each code block. After each code block,
+   include a short paragraph describing the resulting state and why it matters.
+5. Keep the instructional tone precise.
+   Use a book-like instructional narrative while staying professional and
+   direct. Imperative phrasing is preferred. Limited second-person phrasing is
+   acceptable when it clearly improves the instruction.
+6. Keep terminology and examples consistent.
+   Define acronyms on first use, use terms such as `GPU`, `CPU`, `wgpu`,
+   `bind group`, and `pipeline layout` consistently, and refer to identifiers
+   with backticks.
+7. Keep code snippets minimal and repository-aligned.
+   Match repository style: 2-space indentation, line width near 80 columns,
+   explicit return statements, and no abbreviations or acronyms in code
+   identifiers. Prefer workspace-relative file paths in prose and examples.
+8. Update maintenance metadata on substantive edits.
+   Update `last_updated`, bump `version` semantically, set `repo_commit` to
+   `HEAD`, and maintain the `Changelog`.
+
+## Required Style Rules
+
+- Use clear, direct, neutral language.
+- Prefer active voice and present tense.
+- Avoid conversational filler, rhetorical questions, emojis, marketing claims,
+  speculation, and AI authorship references.
+- Use RFC-2119 keywords in `Notes` when the content is normative.
+- Do not include commentary about internal process documents or guideline
+  updates.
+
+## Validation Checklist
+
+- The tutorial lives under `docs/tutorials/` with a kebab-case file name.
+- Metadata header and `tutorial` tag are present.
+- A table of contents is present.
+- All required sections are present and ordered clearly.
+- Each implementation step includes intent before the code and outcome after it.
+- Code snippets are minimal, buildable, and repository-aligned.
+- `Validation` contains exact commands and expected behavior.
+- `Exercises` contains 5 to 7 focused follow-up tasks.

.codex/skills/tutorial-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Tutorial Authoring"
+  short_description: "Write repository tutorials with the required structure"
+  default_prompt: "Use $tutorial-authoring to create or revise a tutorial for this repository."