constella 0.1.0

package/skills/languages/php/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: php
+description: General-purpose server-side scripting language for the web; consult for PHP syntax, OOP, Composer, and install/setup.
+domain: language
+category: language
+tags: [php, server-side, web, scripting, backend]
+official_sources:
+  - https://www.php.net/docs.php
+  - https://github.com/php/php-src
+verified: 2026-06-16
+---
+
+# PHP
+
+## Overview
+PHP is a popular general-purpose scripting language especially suited to web development; it powers a large share of the web from blogs to major sites. Code is embedded in or generated alongside HTML and executed server-side. Read this when building web backends in PHP, working with Composer packages, or setting up a PHP runtime.
+
+## Official sources
+- Docs: https://www.php.net/docs.php
+- Repo: https://github.com/php/php-src
+- Install / download: https://www.php.net/downloads
+
+## Install / setup
+The official downloads page shows per-OS instructions. For Debian/Ubuntu it lists, verbatim:
+
+```bash
+# Update the package lists.
+sudo apt update
+
+# Install PHP.
+sudo apt install -y php
+```
+
+Source: https://www.php.net/downloads (current stable versions listed there include 8.5, 8.4, 8.3, 8.2)
+
+## Core concepts
+- Request lifecycle — PHP scripts typically run per HTTP request and exit; state does not persist across requests unless stored (session, DB, cache).
+- Types and weak/strict typing — PHP is dynamically typed but supports type declarations and `declare(strict_types=1)` for strict scalar typing.
+- Classes, interfaces, traits, and enumerations — full OOP model; traits share method implementations across classes.
+- Namespaces — organize and disambiguate classes/functions to avoid collisions.
+- Superglobals and predefined variables — `$_GET`, `$_POST`, `$_SESSION`, `$_SERVER` expose request and environment data.
+- Composer — the de facto dependency manager and PSR-4 autoloader for PHP libraries.
+- Errors, exceptions, generators, fibers, and attributes are part of the modern language reference.
+
+## Best practices
+- Enable `declare(strict_types=1)` and use type declarations to catch type errors early (see php.net Language Reference: Types).
+- Follow the Security section of the docs: validate and escape all user-submitted data, use prepared statements for databases.
+- Manage dependencies and autoloading with Composer rather than manual `require` chains.
+- Keep PHP on a supported version (php.net lists active versions) and apply security releases promptly.
+
+## Common pitfalls
+- Concatenating user input into SQL → use parameterized/prepared statements (PDO or mysqli) to prevent injection.
+- Echoing unescaped user data into HTML → escape output (`htmlspecialchars`) to prevent XSS, per the docs' security guidance.
+- Relying on loose comparison (`==`) where type juggling surprises (e.g. `"0" == false`) → use strict comparison (`===`).
+
+## Examples
+```php
+<?php
+declare(strict_types=1);
+
+function greet(string $name): string {
+    return "Hello, " . htmlspecialchars($name);
+}
+
+echo greet($_GET['name'] ?? 'world');
+```
+
+## Further reading
+- Language reference: https://www.php.net/docs.php
+- Security considerations: https://www.php.net/docs.php (Security section)
+
+## Related skills
+- ../ruby — dynamic scripting language comparison
+- ../../stacks — PHP web frameworks (Laravel, Symfony) consume this language

package/skills/languages/python/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: python
+description: Batteries-included, general-purpose dynamic language; consult for core syntax, the standard library, and environments.
+domain: language
+category: language
+tags: [python, cpython, scripting, stdlib, venv]
+official_sources:
+  - https://docs.python.org/3/
+  - https://github.com/python/cpython
+  - https://www.python.org/downloads/
+verified: 2026-06-16
+---
+
+# Python
+
+## Overview
+Python is a high-level, general-purpose programming language emphasizing readability and a large standard library ("batteries included"). It is dynamically typed, garbage-collected, and supports procedural, object-oriented, and functional styles. CPython is the reference implementation. Read this for core syntax, packaging/virtual environments, and standard-library usage.
+
+## Official sources
+- Docs: https://docs.python.org/3/
+- Repo (CPython reference implementation): https://github.com/python/cpython
+- Install / download: https://www.python.org/downloads/
+
+## Install / setup
+Download and run the installer for your platform from https://www.python.org/downloads/. Verify the install:
+```bash
+python3 --version
+```
+
+## Core concepts
+- Indentation-defined blocks: whitespace (not braces) delimits code blocks; consistent indentation is syntactically required.
+- Dynamic typing with strong typing: names are bound to objects of any type at runtime, but Python does not silently coerce unrelated types.
+- Everything is an object: functions, classes, and modules are first-class objects; duck typing drives polymorphism.
+- The standard library: a broad set of built-in modules (os, json, pathlib, datetime, itertools, etc.) cover common tasks without third-party packages.
+- Virtual environments: `venv` isolates per-project dependencies from the system interpreter.
+- Iterators, generators, and comprehensions: lazy iteration via `__iter__`/`yield`; concise list/dict/set comprehensions.
+- Exceptions: errors are raised and caught with `try`/`except`/`finally`; use specific exception types.
+
+## Best practices
+- Follow PEP 8, the official style guide, for layout, naming, and formatting.
+- Use a virtual environment (`python3 -m venv .venv`) per project so dependencies don't collide with the system Python.
+- Prefer context managers (`with open(...) as f:`) so resources are released deterministically.
+- Catch specific exceptions rather than bare `except:`; let unexpected errors surface.
+
+## Common pitfalls
+- Mutable default arguments (`def f(x=[]):`) → the default is created once and shared across calls; use `None` and create inside the function.
+- Mixing tabs and spaces for indentation → causes `TabError`/inconsistent blocks; use spaces consistently (PEP 8 recommends 4 spaces).
+- Relying on dict/iteration order assumptions across versions → insertion order is guaranteed for dicts in modern CPython, but don't depend on set ordering.
+- Installing packages into the system interpreter globally → use a virtual environment to avoid conflicts.
+
+## Examples
+```python
+from pathlib import Path
+
+def read_lines(path: str) -> list[str]:
+    with open(path, encoding="utf-8") as f:
+        return [line.rstrip("\n") for line in f]
+
+for line in read_lines("data.txt"):
+    print(line)
+```
+
+## Further reading
+- The Python Tutorial: https://docs.python.org/3/tutorial/
+- PEP 8 style guide: https://peps.python.org/pep-0008/
+
+## Related skills
+- (sibling language skills under ../)

package/skills/languages/r/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: r
+description: R is a free language and environment for statistical computing, data analysis, and graphics, with packages distributed via CRAN; consult when writing R, installing packages, using vectors/data frames, the tidyverse, ggplot2, or producing statistical models, plots, and reproducible analyses.
+domain: language
+category: language
+tags: [r, statistics, data-analysis, cran, tidyverse, ggplot2, vectorized]
+official_sources:
+  - https://www.r-project.org/
+  - https://cran.r-project.org/
+  - https://cran.r-project.org/manuals.html
+verified: 2026-06-17
+---
+
+# R
+
+## Overview
+R is a free software environment and language for statistical computing, data analysis, and graphics, maintained by the R Foundation with packages distributed through CRAN. It is vectorized by design and excels at statistical modeling, data manipulation, and visualization. Read this when writing R, installing/using packages, working with data frames and the tidyverse, or producing plots and reproducible analyses.
+
+## Official sources
+- Docs: https://www.r-project.org/
+- Repo: https://svn.r-project.org/R/ (official SVN; GitHub mirror at https://github.com/r-devel/r-svn)
+- Install: https://cran.r-project.org/
+
+## Install / setup
+```r
+# After installing R from CRAN, install packages from within R:
+install.packages("tidyverse")
+library(tidyverse)
+```
+Download R per https://cran.r-project.org/ ; `install.packages` is the official package-install function (https://cran.r-project.org/manuals.html).
+
+## Core concepts
+- **Vectors & vectorization** — the atomic vector is the base type; operations apply element-wise without explicit loops.
+- **Data frames / tibbles** — tabular data with typed columns; the core structure for analysis.
+- **Factors** — categorical variables with defined levels, important for modeling.
+- **Functions & lazy/promise args** — first-class functions; arguments evaluated lazily when used.
+- **The `<-` assignment** — idiomatic assignment operator (vs `=`), plus `%>%`/`|>` pipes for chaining.
+- **CRAN & packages** — `install.packages()` / `library()` pull from the Comprehensive R Archive Network.
+- **Recycling rule** — shorter vectors recycle to match longer ones in arithmetic; a common gotcha.
+- **Formula objects** — `y ~ x` notation drives `lm`, `glm`, and many modeling functions.
+
+## Best practices
+- Organize work as projects with `renv` for reproducible package versions (https://cran.r-project.org/web/packages/renv/).
+- Prefer vectorized operations and `apply`/`purrr::map` over explicit `for` loops (https://cran.r-project.org/doc/manuals/r-release/R-intro.html).
+- Use the tidyverse (`dplyr`, `ggplot2`, `tidyr`) for readable data pipelines (https://www.tidyverse.org/).
+- Document analyses in R Markdown / Quarto for reproducibility (https://cran.r-project.org/doc/manuals/r-release/R-exts.html).
+
+## Common pitfalls
+- Silent vector recycling producing wrong results → ensure operands have compatible lengths.
+- `stringsAsFactors` and unexpected factor coercion → set explicitly or use `read.csv(..., stringsAsFactors = FALSE)` (default FALSE since R 4.0).
+- Using `=` where `<-` is expected (or vice versa) in calls → use `<-` for assignment, `=` for named arguments.
+
+## Examples
+```r
+library(dplyr)
+
+mtcars |>
+  group_by(cyl) |>
+  summarise(mean_mpg = mean(mpg), n = n()) |>
+  arrange(desc(mean_mpg))
+```
+
+## Further reading
+- https://cran.r-project.org/manuals.html — official R manuals (Intro, Language Definition, Writing Extensions)
+- https://cran.r-project.org/doc/manuals/r-release/R-intro.html — An Introduction to R
+- https://www.tidyverse.org/ — the tidyverse package collection
+
+## Related skills
+- ../clojure — another data-oriented functional language
+- ../haskell — statically typed functional language for comparison

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