constellai 0.3.0

package/skills/languages/ruby/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ruby
+description: Dynamic, object-oriented language focused on developer happiness; consult for Ruby syntax, idioms, gems, and install/setup.
+domain: language
+category: language
+tags: [ruby, dynamic, object-oriented, scripting, gems]
+official_sources:
+  - https://www.ruby-lang.org/en/documentation/
+  - https://github.com/ruby/ruby
+verified: 2026-06-16
+---
+
+# Ruby
+
+## Overview
+Ruby is an interpreted, dynamic, object-oriented programming language created by Yukihiro "Matz" Matsumoto in 1995, designed to make programmers productive and happy. Everything in Ruby is an object, and the language emphasizes readable, expressive syntax. Read this when writing Ruby scripts, working with gems, or setting up a Ruby toolchain.
+
+## Official sources
+- Docs: https://www.ruby-lang.org/en/documentation/
+- Repo: https://github.com/ruby/ruby
+- Install / download: https://www.ruby-lang.org/en/downloads/
+
+## Install / setup
+On Windows, the official downloads page recommends RubyInstaller; on macOS and Linux/UNIX it recommends third-party version managers (rbenv and RVM) or the distribution package manager. From the official downloads page, using a version manager:
+
+```bash
+# Linux/UNIX or macOS via rbenv (third-party tool recommended on ruby-lang.org)
+rbenv install 4.0.5
+rbenv global 4.0.5
+```
+
+Source: https://www.ruby-lang.org/en/downloads/ (current stable listed there is Ruby 4.0.5; substitute the version you need)
+
+## Core concepts
+- Everything is an object — integers, strings, and even `nil` respond to methods; there are no primitives.
+- Dynamic typing with duck typing — an object's suitability is determined by the methods it responds to, not its declared class.
+- Blocks, procs, and lambdas — first-class chunks of code passed to methods (e.g. `each`, `map`); the foundation of Ruby iteration.
+- Mixins via modules — share behavior across classes with `include`/`extend` instead of multiple inheritance.
+- Open classes and metaprogramming — classes can be reopened and methods defined at runtime (`define_method`, `method_missing`).
+- Gems and Bundler — RubyGems packages libraries; Bundler resolves and locks dependencies via a `Gemfile`.
+- Exceptions, iterators, closures, and garbage collection are built into the core language.
+
+## Best practices
+- Follow a community style guide (RuboCop, Shopify, GitLab, or Airbnb guides are linked from ruby-lang.org) and run RuboCop to enforce it.
+- Use Bundler with a committed `Gemfile.lock` for reproducible dependency installs.
+- Prefer iterators and blocks (`each`, `map`, `select`) over manual index loops for idiomatic, readable code.
+- Use a version manager (rbenv/RVM) so each project can pin a known Ruby version.
+
+## Common pitfalls
+- Treating `nil` as falsy-only — in Ruby only `nil` and `false` are falsy; `0` and `""` are truthy. → Test explicitly when you mean numeric/empty.
+- Mutating shared mutable state through reopened classes ("monkey patching") → prefer refinements or composition to limit scope.
+- Forgetting that assignment in blocks can leak or shadow variables → keep block-local variables explicit and small.
+
+## Examples
+```ruby
+# Blocks and iterators
+names = ["ada", "grace", "linus"]
+names.map { |n| n.capitalize }.each { |n| puts "Hello, #{n}" }
+```
+
+## Further reading
+- Official documentation hub: https://www.ruby-lang.org/en/documentation/
+- API docs for all versions: https://docs.ruby-lang.org/en/
+
+## Related skills
+- ../python — another dynamic, batteries-included scripting language
+- ../php — server-side scripting comparison

package/skills/languages/rust/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: rust
+description: Memory-safe systems language with ownership and no GC; consult for ownership/borrowing, Cargo, and error handling.
+domain: language
+category: language
+tags: [rust, systems, ownership, borrow-checker, cargo]
+official_sources:
+  - https://doc.rust-lang.org/book/
+  - https://github.com/rust-lang/rust
+  - https://www.rust-lang.org/tools/install
+verified: 2026-06-16
+---
+
+# Rust
+
+## Overview
+Rust is a systems programming language focused on performance, reliability, and productivity. Its type system and ownership model guarantee memory safety and thread safety without a garbage collector, catching whole classes of bugs at compile time. It ships with Cargo (build tool and package manager), rustfmt, Clippy, and rust-analyzer. Read this for ownership/borrowing, error handling, and the Cargo workflow.
+
+## Official sources
+- Docs (The Book): https://doc.rust-lang.org/book/
+- Repo: https://github.com/rust-lang/rust
+- Install: https://www.rust-lang.org/tools/install
+
+## Install / setup
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+## Core concepts
+- Ownership: every value has a single owner; when the owner goes out of scope the value is dropped (deterministic deallocation, no GC).
+- Borrowing and references: values can be borrowed immutably (`&T`, many) or mutably (`&mut T`, exactly one at a time); the borrow checker enforces this at compile time.
+- Lifetimes: the compiler tracks how long references are valid to prevent dangling references; most are inferred, some are annotated.
+- Traits: shared behavior defined as traits and implemented for types; the basis for generics and polymorphism.
+- Enums and pattern matching: algebraic data types with `match`; `Option<T>` and `Result<T, E>` replace null and exceptions.
+- Error handling: recoverable errors use `Result` with the `?` operator; unrecoverable errors `panic!`.
+- Cargo: builds, tests, runs, and manages dependencies via `Cargo.toml` from crates.io.
+
+## Best practices
+- Let the borrow checker guide design: prefer borrowing over cloning, and restructure data flow rather than reaching for `unsafe`.
+- Use `Result` and the `?` operator for recoverable errors; reserve `panic!`/`unwrap` for truly unrecoverable states or tests.
+- Run `cargo clippy` (the official linter) and `cargo fmt` to keep code idiomatic and consistent.
+- Model invalid states out of existence with enums and the type system instead of runtime checks.
+
+## Common pitfalls
+- Reaching for `.unwrap()`/`.expect()` in production paths → propagate with `?` and handle `None`/`Err` explicitly.
+- Fighting the borrow checker by cloning everywhere → often a sign the data ownership/structure needs rethinking.
+- Overusing `unsafe` to bypass the checker → it disables guarantees; isolate and justify any `unsafe` block.
+- Confusing `String` (owned) with `&str` (borrowed slice) → pass `&str` for read-only access, own a `String` when you need to store/grow it.
+
+## Examples
+```rust
+use std::fs;
+
+fn read_config(path: &str) -> Result<String, std::io::Error> {
+    let contents = fs::read_to_string(path)?; // ? propagates the error
+    Ok(contents)
+}
+
+fn main() {
+    match read_config("config.toml") {
+        Ok(text) => println!("{text}"),
+        Err(e) => eprintln!("failed to read config: {e}"),
+    }
+}
+```
+
+## Further reading
+- The Rust Programming Language (The Book): https://doc.rust-lang.org/book/
+- Rust by Example: https://doc.rust-lang.org/rust-by-example/
+
+## Related skills
+- ../go — another modern compiled systems-adjacent language

package/skills/languages/scala/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: scala
+description: JVM language blending object-oriented and functional programming with strong static typing; consult for syntax and setup.
+domain: language
+category: language
+tags: [scala, jvm, functional, object-oriented, static-typing]
+official_sources:
+  - https://docs.scala-lang.org/
+  - https://github.com/scala/scala
+verified: 2026-06-16
+---
+
+# Scala
+
+## Overview
+Scala is a statically typed language for the JVM that fuses object-oriented and functional programming, with a powerful type system and concise, expressive syntax. It interoperates with Java libraries and runs on the JVM (with Scala.js and Scala Native as additional targets). Read this when writing Scala, choosing between Scala 2 and 3, or setting up the toolchain.
+
+## Official sources
+- Docs: https://docs.scala-lang.org/
+- Repo: https://github.com/scala/scala
+- Install / download: https://www.scala-lang.org/download/
+
+## Install / setup
+The official download page recommends `cs setup`, the Scala installer powered by Coursier. Verbatim for Linux (x86-64):
+
+```bash
+curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup
+```
+
+macOS (Homebrew), verbatim from the same page:
+
+```bash
+brew install coursier/formulas/coursier && cs setup
+```
+
+Source: https://www.scala-lang.org/download/
+
+## Core concepts
+- Everything is an expression — `if`, `match`, and blocks return values; statements are rare.
+- Immutability by default — `val` (immutable) is preferred over `var`; immutable collections are the default.
+- Pattern matching and case classes — destructure and branch on algebraic data with exhaustive `match` expressions.
+- Traits — composable units of behavior mixed into classes, supporting a flexible alternative to single inheritance.
+- Strong static typing with inference — the compiler infers most types while enforcing safety; supports generics and higher-kinded types.
+- Higher-order functions and the collections library — `map`, `flatMap`, `filter`, `fold` enable functional data transformations.
+- Scala 2 vs Scala 3 — Scala 3 is a separate evolution; docs cover both and a migration guide.
+
+## Best practices
+- Prefer `val` and immutable collections; reach for `var`/mutable state only when measured and necessary.
+- Use case classes and pattern matching for modeling data and control flow idiomatically.
+- Follow the official Scala style guide (linked from docs.scala-lang.org) for idiomatic code.
+- Install and manage tooling with Coursier (`cs setup`), the recommended installer.
+
+## Common pitfalls
+- Overusing mutable `var` and imperative loops → favor immutable values and collection combinators.
+- Non-exhaustive `match` expressions on sealed hierarchies → enable warnings so the compiler flags missing cases.
+- Mixing Scala 2 and Scala 3 assumptions → check which version a feature/library targets (see the migration guide).
+
+## Examples
+```scala
+case class Greeter(prefix: String):
+  def greet(name: String): String = s"$prefix, ${name.capitalize}"
+
+val g = Greeter("Hello")
+List("ada", "grace").map(g.greet).foreach(println)
+```
+
+## Further reading
+- Documentation and tour: https://docs.scala-lang.org/
+- Scala 2 to 3 migration: https://docs.scala-lang.org/ (migration guide)
+
+## Related skills
+- ../elixir — functional programming on another managed VM
+- ../../stacks — JVM/Scala frameworks (e.g. Akka, Play) build on this language

package/skills/languages/swift/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: swift
+description: Apple-backed, memory-safe, high-performance language for apps and systems; consult for Swift syntax, concurrency, and setup.
+domain: language
+category: language
+tags: [swift, apple, memory-safe, systems, ios]
+official_sources:
+  - https://www.swift.org/documentation/
+  - https://github.com/swiftlang/swift
+verified: 2026-06-16
+---
+
+# Swift
+
+## Overview
+Swift is a high-performance, memory-safe systems and application programming language with a clean modern syntax and seamless access to existing C and Objective-C code and frameworks. It powers Apple-platform apps and increasingly server-side and cross-platform software on Linux and Windows. Read this when writing Swift, designing with its concurrency model, or setting up the toolchain.
+
+## Official sources
+- Docs: https://www.swift.org/documentation/
+- Repo: https://github.com/swiftlang/swift
+- Install / download: https://www.swift.org/install/
+
+## Install / setup
+The official Linux install page recommends Swiftly, the Swift toolchain installer. Verbatim (Bash):
+
+```bash
+curl -O https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz && \
+tar zxf swiftly-$(uname -m).tar.gz && \
+./swiftly init --quiet-shell-followup && \
+. "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh" && \
+hash -r
+```
+
+Source: https://www.swift.org/install/linux/ (macOS and Windows installers: https://www.swift.org/install/)
+
+## Core concepts
+- Value vs reference types — `struct`/`enum` are value types (copied), `class` is a reference type; choosing correctly shapes behavior and performance.
+- Optionals — the type system encodes the possible absence of a value (`T?`), forcing explicit handling of nil.
+- Protocols and protocol-oriented programming — define capabilities and provide default implementations via extensions.
+- Automatic Reference Counting (ARC) — memory for class instances is managed by reference counts; watch for retain cycles.
+- Error handling — typed `throws`/`try`/`catch` with `Result` for explicit, recoverable error flows.
+- Structured concurrency — `async`/`await`, tasks, and actors provide safe, composable asynchronous and concurrent code.
+
+## Best practices
+- Prefer value types (`struct`/`enum`) and immutability (`let`) by default; reach for `class` only when reference semantics are needed.
+- Handle optionals explicitly with `if let`/`guard let` rather than force-unwrapping (`!`).
+- Use protocol extensions to share behavior instead of deep class hierarchies.
+- Manage Swift toolchain versions with Swiftly (the official installer) for reproducible builds.
+
+## Common pitfalls
+- Force-unwrapping optionals (`value!`) that can be nil → crashes at runtime; use optional binding or `??` defaults.
+- Strong reference cycles between classes/closures → use `weak`/`unowned` captures to let ARC reclaim memory.
+- Sharing mutable state across concurrent tasks → isolate it inside an `actor` to avoid data races.
+
+## Examples
+```swift
+struct Greeter {
+    func greet(_ name: String?) -> String {
+        guard let name, !name.isEmpty else { return "Hello, world" }
+        return "Hello, \(name.capitalized)"
+    }
+}
+
+print(Greeter().greet("ada"))
+```
+
+## Further reading
+- Documentation hub: https://www.swift.org/documentation/
+- Install guides per platform: https://www.swift.org/install/
+
+## Related skills
+- ../cpp — the C/C++ systems languages Swift interoperates with
+- ../../stacks — Swift app/server frameworks build on this language

package/skills/languages/typescript/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: typescript
+description: Typed superset of JavaScript that compiles to plain JS; consult for type system, tsconfig, and compiler usage.
+domain: language
+category: language
+tags: [typescript, javascript, types, compiler, tsc]
+official_sources:
+  - https://www.typescriptlang.org/docs/
+  - https://github.com/microsoft/TypeScript
+  - https://www.typescriptlang.org/download
+verified: 2026-06-16
+---
+
+# TypeScript
+
+## Overview
+TypeScript is a strongly typed programming language that builds on JavaScript by adding optional static types, then compiles down to plain JavaScript that runs anywhere JavaScript runs. It catches whole classes of errors before runtime and powers richer editor tooling for large-scale applications. Read this when configuring a TypeScript build, designing types, or debugging compiler errors.
+
+## Official sources
+- Docs: https://www.typescriptlang.org/docs/
+- Repo: https://github.com/microsoft/TypeScript
+- Install / download: https://www.typescriptlang.org/download
+
+## Install / setup
+```bash
+npm install typescript --save-dev
+```
+
+## Core concepts
+- Structural typing: types are compatible based on their shape (members), not their declared name; an object satisfying an interface's members is assignable to it.
+- Type annotations and inference: annotate variables, parameters, and return types, but lean on the compiler's inference where it already knows the type.
+- Interfaces and type aliases: model object shapes and unions; `interface` is open to declaration merging, `type` can express unions, intersections, and mapped types.
+- Generics: write reusable, type-safe components and functions parameterized over types (`Array<T>`, `Promise<T>`).
+- Union, intersection, and literal types: combine types and narrow them with control-flow analysis (type guards) to model precise states.
+- `tsconfig.json`: the project configuration file controlling the compiler — target, module system, `strict` flags, and which files are included.
+- The `tsc` compiler: type-checks and emits JavaScript; type errors do not necessarily block emit unless configured to.
+
+## Best practices
+- Enable `strict` mode in `tsconfig.json` — it turns on the full family of strict type-checking options recommended by the docs for catching more bugs.
+- Prefer letting the compiler infer types for locals; annotate public API boundaries (function signatures, exported values) explicitly.
+- Avoid `any`; prefer `unknown` when a value's type is genuinely not known, then narrow it before use.
+- Use union types and discriminated unions plus exhaustiveness checking instead of loose runtime type juggling.
+
+## Common pitfalls
+- Treating TypeScript types as runtime values → types are erased at compile time; use runtime checks (`typeof`, validation libraries) for runtime guarantees.
+- Assuming a clean `tsc` build means the JS won't run on errors → by default emit can still occur; use `noEmitOnError` if you want errors to block output.
+- Overusing `any` to silence errors → it disables checking and propagates; prefer `unknown`, generics, or proper narrowing.
+
+## Examples
+```typescript
+interface User {
+  id: number;
+  name: string;
+}
+
+function greet(user: User): string {
+  return `Hello, ${user.name}`;
+}
+
+const u: User = { id: 1, name: "Ada" };
+console.log(greet(u));
+```
+
+## Further reading
+- TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/intro.html
+- tsconfig reference: https://www.typescriptlang.org/tsconfig/
+
+## Related skills
+- ../javascript — the language TypeScript compiles to

package/skills/meta/authoring-agent-skills/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: authoring-agent-skills
+description: How to author an Agent Skill — a folder + SKILL.md with YAML frontmatter, loaded on demand. Consult when creating or reviewing a skill.
+domain: meta
+category: meta
+tags: [agent-skills, skill-md, frontmatter, claude, authoring]
+official_sources:
+  - https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+  - https://github.com/anthropics/skills
+verified: 2026-06-16
+---
+
+# Authoring Agent Skills
+
+## Overview
+An Agent Skill is a folder containing a `SKILL.md` file that packages instructions, metadata, and optional resources (scripts, reference docs, templates) that an agent loads automatically when a task is relevant. Skills turn a general-purpose agent into a specialist without bloating the system prompt, because only lightweight metadata is loaded up front. Read this when you need to create a new skill, fix one that is not being discovered, or review a skill's structure against the spec.
+
+## Official sources
+- Docs (overview): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Docs (authoring best practices): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+- Repo (official examples + template + spec): https://github.com/anthropics/skills
+- Open spec: https://agentskills.io/specification
+
+## Core concepts
+- **A skill is a directory.** At minimum it holds a top-level `SKILL.md`; optional `scripts/`, `references/`, and `assets/` subfolders carry code and reference material (per the open spec at agentskills.io).
+- **`SKILL.md` = YAML frontmatter + Markdown body.** The frontmatter is metadata for discovery; the body is the procedural instructions the agent follows once the skill activates.
+- **Two required frontmatter fields:** `name` (max 64 chars, lowercase letters/numbers/hyphens, no reserved words `anthropic`/`claude`) and `description` (non-empty, max 1024 chars). Both must avoid XML tags.
+- **Three loading levels (progressive disclosure).** Level 1 metadata (name + description, ~100 tokens) is always loaded at startup; Level 2 is the `SKILL.md` body, loaded only when the skill is triggered; Level 3 is bundled files/scripts, read or executed on demand without consuming context until accessed.
+- **Discovery is description-driven.** At startup only each skill's `name` and `description` enter the system prompt, so the agent decides whether to read the full `SKILL.md` based almost entirely on the description.
+- **Scripts run, not read.** Utility scripts in `scripts/` are executed via bash; only their output enters context, making them more reliable and cheaper than asking the agent to regenerate code.
+
+## Best practices
+- Write the `description` in third person and state both *what the skill does* and *when to use it*, including concrete trigger keywords — it is the single most important field for discovery (best-practices guide).
+- Keep the `SKILL.md` body under 500 lines; split deeper material into separate reference files that the body links to (best-practices guide, "Progressive disclosure patterns").
+- Use gerund-form names where it reads naturally (`processing-pdfs`, `analyzing-spreadsheets`); avoid vague names like `helper`, `utils`, or `tools` (best-practices guide, "Naming conventions").
+- Assume the agent is already capable: only add context it does not already have, and challenge each sentence for its token cost (best-practices guide, "Concise is key").
+- Match degrees of freedom to task fragility: high-freedom prose for open-ended work, exact low-freedom commands for fragile/destructive steps (best-practices guide, "Set appropriate degrees of freedom").
+
+## Common pitfalls
+- Vague descriptions like "Helps with documents" → write specific descriptions with what + when + keywords so the agent can pick the right skill among many.
+- Windows-style backslash paths in references → always use forward slashes (`scripts/helper.py`); backslashes break on Unix (best-practices guide, "Anti-patterns to avoid").
+- Deeply nested reference chains (`SKILL.md` → `a.md` → `b.md`) → keep all references one level deep from `SKILL.md` so the agent reads complete files instead of partial previews.
+- Using a skill from an untrusted source without auditing it → review every bundled file; a malicious skill can direct the agent to misuse tools or exfiltrate data (overview, "Security considerations").
+
+## Examples
+```markdown
+---
+name: processing-pdfs
+description: Extract text and tables from PDF files, fill forms, and merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+---
+
+# PDF Processing
+
+## Quick start
+Use pdfplumber to extract text:
+
+    import pdfplumber
+    with pdfplumber.open("file.pdf") as pdf:
+        text = pdf.pages[0].extract_text()
+
+## Advanced features
+- Form filling: see references/FORMS.md
+- API reference: see references/REFERENCE.md
+```
+
+## Further reading
+- Best-practices guide (full authoring checklist): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+- Agent Skills open specification: https://agentskills.io/specification
+- Official template + example skills: https://github.com/anthropics/skills
+
+## Related skills
+- ../progressive-disclosure — how to keep SKILL.md short and push depth into on-demand files
+- ../skill-frontmatter-spec — the exact YAML frontmatter fields and their constraints

package/skills/meta/progressive-disclosure/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: progressive-disclosure
+description: Keep SKILL.md short and push depth into on-demand reference files so agents load only what each task needs. Consult when a skill grows large.
+domain: meta
+category: meta
+tags: [progressive-disclosure, agent-skills, context-window, reference-files, token-budget]
+official_sources:
+  - https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+  - https://github.com/anthropics/skills
+verified: 2026-06-16
+---
+
+# Progressive Disclosure
+
+## Overview
+Progressive disclosure is the design principle behind Agent Skills: an agent loads information in stages as a task calls for it, rather than consuming the whole skill up front. A short `SKILL.md` acts like a table of contents that points to deeper reference files, scripts, and assets, which are read or executed only on demand. Read this when a skill is getting long, its body exceeds the recommended budget, or you want bundled reference material to stay out of context until needed.
+
+## Official sources
+- Docs (best practices, "Progressive disclosure patterns"): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+- Docs (overview, "How Skills work"): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Open spec ("Progressive disclosure"): https://agentskills.io/specification
+- Repo (official examples): https://github.com/anthropics/skills
+
+## Core concepts
+- **Three loading levels.** Level 1: metadata (`name` + `description`, ~100 tokens) loaded at startup for every skill. Level 2: the `SKILL.md` body, loaded when the skill triggers. Level 3: bundled files in `scripts/`, `references/`, `assets/`, loaded only when actually accessed.
+- **The context window is a shared public good.** Once `SKILL.md` is loaded, every token competes with conversation history and other skills' metadata — conciseness still matters even though bundled files are free until read (best-practices, "Concise is key").
+- **Bundled content has no context penalty until used.** A skill can ship comprehensive API docs, large datasets, or many examples; files consume zero tokens until the agent reads them (overview, "Level 3").
+- **Scripts execute without entering context.** Running `validate.py` via bash brings only its output into context, not the source — cheaper and more reliable than regenerating equivalent code.
+- **`SKILL.md` is a navigation hub.** Treat it like an onboarding guide's table of contents that links to the right detailed file for each branch of the task.
+
+## Best practices
+- Keep the `SKILL.md` body under 500 lines; split content into separate files as you approach the limit (best-practices, "Token budgets").
+- Keep file references one level deep from `SKILL.md` so the agent reads complete files instead of partial `head -100` previews (best-practices, "Avoid deeply nested references").
+- Organize reference files by domain (`reference/finance.md`, `reference/sales.md`) so a query about one domain never pulls in unrelated context (best-practices, "Pattern 2: Domain-specific organization").
+- Add a table of contents to any reference file longer than ~100 lines so the agent can see its full scope even when previewing (best-practices, "Structure longer reference files").
+- Use forward slashes in all paths so references resolve across platforms (best-practices, "Anti-patterns to avoid").
+
+## Common pitfalls
+- Cramming every detail into `SKILL.md` → move advanced/edge-case material into linked reference files that load only when relevant.
+- Deeply nested reference chains (`SKILL.md` → `advanced.md` → `details.md`) → the agent may read referenced-from-referenced files only partially; keep all links one level deep from `SKILL.md`.
+- Over-explaining things the agent already knows → trim it; padding `SKILL.md` raises token cost without adding signal (best-practices, "Default assumption: Claude is already very smart").
+
+## Examples
+```markdown
+# BigQuery Data Analysis
+
+## Available datasets
+- Finance: revenue, ARR, billing — see reference/finance.md
+- Sales: opportunities, pipeline — see reference/sales.md
+- Product: API usage, adoption — see reference/product.md
+
+## Quick search
+Find metrics with grep:
+
+    grep -i "revenue" reference/finance.md
+```
+The body stays tiny; `reference/finance.md` is read only when a query is about finance, leaving the other reference files at zero token cost.
+
+## Further reading
+- Overview, "Three types of Skill content, three levels of loading": https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Best-practices authoring checklist: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+
+## Related skills
+- ../authoring-agent-skills — the overall skill folder + SKILL.md format
+- ../skill-frontmatter-spec — the metadata fields loaded at Level 1

package/skills/meta/skill-frontmatter-spec/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: skill-frontmatter-spec
+description: SKILL.md YAML frontmatter fields (name, description, license, compatibility, metadata, allowed-tools) and constraints. Consult when writing frontmatter.
+domain: meta
+category: meta
+tags: [frontmatter, yaml, agent-skills, skill-md, spec]
+official_sources:
+  - https://agentskills.io/specification
+  - https://github.com/agentskills/agentskills
+verified: 2026-06-16
+---
+
+# SKILL.md Frontmatter Spec
+
+## Overview
+Every Agent Skill begins with YAML frontmatter at the top of its `SKILL.md`. Two fields are required (`name`, `description`); the open Agent Skills specification also defines optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and clients may add their own (unknown fields are ignored for forward compatibility). Read this when authoring frontmatter, debugging why a skill fails validation, or aligning frontmatter conventions across repos like anthropics/skills, vercel-labs/agent-skills, and remotion-dev/skills.
+
+## Official sources
+- Spec (full frontmatter table + per-field rules): https://agentskills.io/specification
+- Spec repo + `skills-ref` validator: https://github.com/agentskills/agentskills
+- Anthropic field requirements (overview, "Skill structure"): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
+- Example skills using this frontmatter: https://github.com/anthropics/skills · https://github.com/vercel-labs/agent-skills · https://github.com/remotion-dev/skills
+
+## Core concepts
+- **`name` (required).** 1–64 chars, lowercase letters/numbers/hyphens only (`^[a-z0-9]+(-[a-z0-9]+)*$`), no leading/trailing or consecutive hyphens, and must match the parent directory name. Anthropic's docs additionally forbid the reserved words `anthropic` and `claude` and any XML tags.
+- **`description` (required).** 1–1024 chars, non-empty, no XML tags; should state what the skill does and when to use it, with discovery keywords. It is loaded into the system prompt at startup, so it drives skill selection.
+- **`license` (optional).** A license name or a reference to a bundled license file; keep it short (spec, `license` field).
+- **`compatibility` (optional).** Up to 500 chars describing environment needs (intended product, required system packages, network access). Most skills omit it (spec, `compatibility` field).
+- **`metadata` (optional).** An arbitrary string-to-string map for client-specific data such as `author` and `version`; use reasonably unique keys to avoid conflicts (spec, `metadata` field).
+- **`allowed-tools` (optional, experimental).** A space-separated string of pre-approved tools, e.g. `Bash(git:*) Bash(jq:*) Read`; support varies by agent implementation (spec, `allowed-tools` field).
+
+## Best practices
+- Make the `name` exactly match the skill's directory name — the spec requires it and validators enforce it.
+- Validate frontmatter with the reference tool before shipping: `skills-ref validate ./my-skill` (spec, "Validation").
+- Quote ambiguous YAML scalars (e.g. `version: "1.0"`) so they are not parsed as numbers (spec `metadata` example uses quotes).
+- Treat the `description` as a discovery surface: front-load distinctive keywords and the triggering context, since it is the metadata loaded for every skill at startup (Anthropic best-practices, "Writing effective descriptions").
+- Only add `compatibility` when the skill genuinely has environment requirements; leaving it off keeps metadata lean (spec note: "Most skills do not need the `compatibility` field").
+
+## Common pitfalls
+- Uppercase, leading/trailing, or consecutive hyphens in `name` (`PDF-Processing`, `-pdf`, `pdf--processing`) → use lowercase, single-hyphen-separated tokens matching the regex.
+- `name` that differs from the folder name → rename one so they match, or validation fails.
+- Putting custom keys at the top level of the frontmatter → nest non-spec data under `metadata` so it is treated as client metadata rather than an unknown/ignored field.
+- Embedding XML tags or exceeding length limits in `name`/`description` → both fields reject XML tags, and they cap at 64 and 1024 characters respectively.
+
+## Examples
+```yaml
+---
+name: pdf-processing
+description: Extract PDF text, fill forms, merge files. Use when handling PDFs, forms, or document extraction.
+license: Apache-2.0
+compatibility: Requires Python 3.14+ and uv
+metadata:
+  author: example-org
+  version: "1.0"
+allowed-tools: Bash(git:*) Read
+---
+```
+
+## Further reading
+- Full specification with valid/invalid examples per field: https://agentskills.io/specification
+- Anthropic frontmatter requirements + description guidance: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+
+## Related skills
+- ../authoring-agent-skills — the skill folder + SKILL.md format the frontmatter belongs to
+- ../progressive-disclosure — how the frontmatter metadata enables on-demand loading

package/skills/process/adr-technical-decisions/SKILL.md

@@ -0,0 +1,59 @@
+# Skill — adr-technical-decisions
+
+**Trigger:** An architecturally significant technical decision is being made (stack choice, data model, integration approach, cross-cutting pattern) and must be recorded as an Architecture Decision Record before or as it is committed.
+
+Produces a single immutable ADR file capturing the decision, its context, and its consequences, added to the project's decision log.
+
+## When to use
+- Choosing a load-bearing technology, library, protocol, or pattern.
+- Making a trade-off whose rationale future maintainers will need (and would otherwise guess at).
+- Reversing or superseding an earlier architectural decision.
+
+## When NOT to use
+- A reversible, low-impact implementation detail with no real trade-off (just do it; a comment suffices).
+- The decision isn't made yet and you're still prioritizing options — use `process/prioritization-moscow-rice` first, then record the outcome here.
+- General planning (use `process/app-planning`); an ADR records *one* decision, not a whole plan.
+
+## Required context & inputs
+- The decision being made and the forces/constraints driving it.
+- The alternatives considered and why they were or weren't chosen.
+- The existing ADR directory and the next sequence number (check `docs/adr/` or the org's convention).
+- The org's stack and constraints (from `.claude/CLAUDE.md`).
+
+## Procedure
+1. **Confirm it's architecturally significant.** An ADR documents "a justified design choice that addresses a functional or non-functional requirement that is architecturally significant." If the choice is trivial or easily reversed, don't spend an ADR on it.
+2. **Locate the decision log.** Find the ADR directory (commonly `docs/adr/` or `doc/architecture/decisions/`). All ADRs together form the project's **decision log** — the chronological record of architectural choices. If none exists, create the directory and start the sequence at `0001`.
+3. **Assign a sequential number and title.** Number ADRs monotonically (`0001`, `0002`, …) so order is preserved. Title it as a short noun phrase naming the decision (e.g. "0007 — Use Drizzle for the ORM").
+4. **Write the ADR using the standard sections** (Nygard format):
+   - **Title** — the numbered short phrase.
+   - **Status** — one of: proposed, accepted, deprecated, or superseded by ADR-NNNN.
+   - **Context** — the forces at play: the problem, constraints, and assumptions that make this decision necessary. State alternatives considered.
+   - **Decision** — the choice made, stated in active voice ("We will …").
+   - **Consequences** — what becomes easier *and* harder as a result; the trade-offs accepted, including downsides.
+5. **Keep ADRs immutable.** Once accepted, do not edit the substance of an ADR. If the decision changes, write a **new** ADR and mark the old one `superseded by ADR-NNNN`; mark the new one `supersedes ADR-MMMM`. The log preserves history — never rewrite it.
+6. **Set the status correctly.** Use `proposed` while under discussion, flip to `accepted` when committed. Reflect lifecycle changes via new ADRs, not edits.
+7. **Link from the work.** Reference the ADR from the plan, the relevant C4 view, and ideally the code/PR that implements it, so the rationale is discoverable from the artifact.
+
+## Output format
+- A markdown file `docs/adr/NNNN-<slug>.md` (4-digit number) in the project, containing exactly the sections: Title, Status, Context, Decision, Consequences.
+- The decision log is the ordered set of these files; optionally an index/README listing them with status.
+
+## Quality & validation rules
+- The file has all five sections; an ADR missing Context or Consequences is incomplete.
+- Status is one of the valid lifecycle values and accurate.
+- Context names the alternatives considered and the constraints — not just the winner.
+- Consequences honestly state the downsides/trade-offs, not only benefits.
+- The number is unique and sequential; no gaps reused, no duplicates.
+- Superseded decisions are linked in both directions (old ↔ new); accepted ADRs are never edited in substance.
+
+## Failure handling
+- **Decision later proves wrong** → write a new ADR that supersedes it; never delete or silently edit the original — the wrong turn is part of the record.
+- **Can't articulate consequences** → the decision may be premature; gather more context or spike before recording it as accepted.
+- **No ADR directory or convention** → create `docs/adr/` and seed it with `0001` (e.g. "Record architecture decisions in ADRs") to establish the practice.
+- **Two ADRs grabbed the same number** → renumber the later one and update any links; numbers must stay unique.
+
+## Related
+- Sources:
+  - ADR home / definition — https://adr.github.io/
+  - ADR templates & examples — https://github.com/joelparkerhenderson/architecture-decision-record
+- Skills: `process/app-planning`, `process/prioritization-moscow-rice`