constellai 0.3.0

package/skills/stacks/infra/railway/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: railway
+description: Deploy apps, databases, and services with Git-driven builds; consult for services, variables, environments, and the Railway CLI.
+domain: stack
+category: infra
+tags: [hosting, paas, deploy, database, cli]
+official_sources:
+  - https://docs.railway.com/
+  - https://github.com/railwayapp/cli
+verified: 2026-06-16
+---
+
+# Railway
+
+## Overview
+Railway is a platform-as-a-service for deploying applications, databases, and supporting services from a Git repo or template, with minimal infrastructure configuration. It groups resources into projects and environments and provisions managed databases (Postgres, Redis, etc.) alongside your app. Read this when you need to stand up an app plus its backing services quickly.
+
+## Official sources
+- Docs: https://docs.railway.com/
+- Repo (CLI): https://github.com/railwayapp/cli
+- CLI install: https://docs.railway.com/guides/cli
+
+## Install / setup
+```bash
+npm i -g @railway/cli
+```
+
+## Core concepts
+- Project: the top-level container that groups related services and environments.
+- Service: a deployable unit (your app, a worker, or a managed database) within a project.
+- Environments: isolated copies of a project's services (e.g. production, staging) with their own variables.
+- Variables: environment variables per service/environment, including auto-injected connection strings from linked databases.
+- Deployments: builds triggered from Git pushes or the CLI, producing a running instance with logs.
+- Plugins/databases: managed datastores provisioned into a project and connected via reference variables.
+
+## Best practices
+- Use separate environments for staging and production rather than reusing one environment for both.
+- Reference database connection details via Railway-provided variables instead of hardcoding credentials.
+- Link the local project with the CLI (`railway link`) so commands and `railway run` use the right environment's variables.
+- Keep service config and variables in Railway/version-controlled config rather than ad hoc dashboard edits where possible.
+
+## Common pitfalls
+- Hardcoding a database URL instead of using the injected reference variable → breaks when the database is recreated or rotated.
+- Running commands against the wrong environment → unlink/relink or confirm the active environment before deploying.
+- Forgetting the CLI requires Node.js 16+ for the npm install method (per the docs).
+
+## Examples
+```bash
+# Authenticate, link a project, and deploy
+railway login
+railway link
+railway up
+
+# Run a local command with the project's env vars injected
+railway run npm start
+```
+
+## Further reading
+- https://docs.railway.com/guides/variables — variables and references
+- https://docs.railway.com/guides/environments — environments
+
+## Related skills
+- ../fly-io — similar deploy platform for apps and databases

package/skills/stacks/infra/tailscale/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: tailscale
+description: Zero-config WireGuard mesh VPN; consult for private networking, ACLs, subnet routing, and secure device-to-device connectivity.
+domain: stack
+category: infra
+tags: [vpn, wireguard, networking, mesh, zero-trust]
+official_sources:
+  - https://tailscale.com/kb/
+  - https://github.com/tailscale/tailscale
+verified: 2026-06-16
+---
+
+# Tailscale
+
+## Overview
+Tailscale builds a private mesh network ("tailnet") between your devices using the WireGuard protocol, with automatic NAT traversal and key distribution handled by a coordination server. It removes the need to manually configure WireGuard keys, firewall holes, or a central VPN concentrator. Read this when you need secure, encrypted connectivity between machines, services, or users without exposing public ports.
+
+## Official sources
+- Docs: https://tailscale.com/kb/
+- Repo: https://github.com/tailscale/tailscale
+- Install / download: https://tailscale.com/download
+
+## Install / setup
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+```
+
+## Core concepts
+- Tailnet: the private network of all devices logged into your Tailscale account/organization; each device gets a stable 100.x.y.z address.
+- WireGuard data plane: traffic is end-to-end encrypted directly between peers; the coordination server only brokers keys and metadata, not user traffic.
+- NAT traversal: Tailscale establishes direct peer connections where possible and falls back to encrypted DERP relays when direct paths are blocked.
+- ACLs: a centrally managed policy file defines which devices and identity groups may reach which others, defaulting to deny.
+- Subnet routers: a node can advertise routes so the tailnet reaches non-Tailscale hosts (e.g. an on-prem subnet or cloud VPC).
+- Exit nodes: a node can route all internet traffic for other devices, acting like a traditional full-tunnel VPN egress.
+- MagicDNS: assigns memorable DNS names to devices so you connect by hostname instead of IP.
+
+## Best practices
+- Define least-privilege ACLs rather than relying on the default "allow all" tailnet policy (see Tailscale KB on access control).
+- Use tagged ACL identities (`tag:server`) for servers and CI nodes instead of personal user logins, so access survives staff changes.
+- Apply key expiry and device approval for sensitive tailnets to limit the blast radius of a leaked node.
+- Prefer ephemeral nodes for short-lived/CI workloads so stale devices do not accumulate in the tailnet.
+
+## Common pitfalls
+- Forgetting to enable IP forwarding and `--advertise-routes` on a subnet router → the advertised subnet is unreachable; routes must also be approved in the admin console.
+- Leaving devices with non-expiring keys → revoking access later is harder; set key expiry per the docs.
+- Assuming all connections are direct → behind strict NATs traffic relays through DERP, adding latency; check `tailscale status` for the relay indicator.
+
+## Examples
+```bash
+# Bring a node onto the tailnet
+sudo tailscale up
+
+# Advertise a local subnet so the tailnet can reach it
+sudo tailscale up --advertise-routes=10.0.0.0/24
+
+# Inspect connectivity and peer relay status
+tailscale status
+```
+
+## Further reading
+- https://tailscale.com/kb/1019/subnets/ — subnet routers
+- https://tailscale.com/kb/1018/acls/ — access control policy
+
+## Related skills
+- ../cloudflare — alternative for tunnels and zero-trust access to private services

package/skills/stacks/infra/terraform/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: terraform
+description: Terraform is HashiCorp's declarative infrastructure-as-code tool using HCL to provision cloud and on-prem resources; consult when writing .tf configs, managing state, using providers/modules, planning and applying changes, or working with variables, outputs, and remote backends.
+domain: stack
+category: infra
+tags: [terraform, iac, hashicorp, hcl, devops, infrastructure, provisioning]
+official_sources:
+  - https://developer.hashicorp.com/terraform/docs
+  - https://github.com/hashicorp/terraform
+  - https://developer.hashicorp.com/terraform/install
+verified: 2026-06-17
+---
+
+# Terraform
+
+## Overview
+Terraform is HashiCorp's infrastructure-as-code tool that lets you define cloud and on-prem infrastructure declaratively in HashiCorp Configuration Language (HCL). It computes an execution plan to reach the desired state and applies it through provider plugins, tracking real-world resources in a state file. Read this when authoring `.tf` configuration, managing state, or running the plan/apply lifecycle.
+
+## Official sources
+- Docs: https://developer.hashicorp.com/terraform/docs
+- Repo: https://github.com/hashicorp/terraform
+- Install: https://developer.hashicorp.com/terraform/install
+
+## Install / setup
+```bash
+brew tap hashicorp/tap
+brew install hashicorp/tap/terraform
+```
+Source: https://developer.hashicorp.com/terraform/install
+
+## Core concepts
+- **HCL** — declarative configuration language used in `.tf` files to describe resources.
+- **Provider** — plugin (e.g. `aws`, `azurerm`) that maps HCL to a target API.
+- **Resource** — a single infrastructure object (`resource "aws_instance" "web" {}`).
+- **State** — recorded mapping of config to real resources (`terraform.tfstate`); source of truth for diffs.
+- **Plan / apply** — `plan` previews changes; `apply` enacts them to converge to desired state.
+- **Module** — reusable, parameterized grouping of resources for composition.
+- **Variable / output** — inputs (`variable`) and exported values (`output`) for configurability.
+- **Backend** — where state is stored (local, S3, Terraform Cloud) enabling remote/locked state.
+
+## Best practices
+- Store state remotely with locking (e.g. S3 + DynamoDB, Terraform Cloud) for team safety (https://developer.hashicorp.com/terraform/language/backend).
+- Always review `terraform plan` output before `apply` (https://developer.hashicorp.com/terraform/cli/commands/plan).
+- Pin provider and module versions with constraints to ensure reproducible runs (https://developer.hashicorp.com/terraform/language/providers/requirements).
+- Structure reusable infrastructure as modules with explicit inputs/outputs (https://developer.hashicorp.com/terraform/language/modules).
+- Run `terraform fmt` and `terraform validate` in CI before merging (https://developer.hashicorp.com/terraform/cli/commands/fmt).
+
+## Common pitfalls
+- Committing `terraform.tfstate` (often with secrets) to git → use a remote backend and gitignore local state.
+- Manual ("click-ops") changes drift from config → run `terraform plan` to detect drift and reconcile.
+- Unpinned versions cause surprise upgrades → set `required_providers` and `required_version` constraints.
+
+## Examples
+```hcl
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+}
+
+provider "aws" { region = "us-east-1" }
+
+resource "aws_s3_bucket" "data" {
+  bucket = "my-app-data-bucket"
+}
+```
+
+## Further reading
+- https://developer.hashicorp.com/terraform/language — HCL language reference
+- https://registry.terraform.io/ — providers and modules registry
+- https://developer.hashicorp.com/terraform/cli/commands — full CLI command reference
+
+## Related skills
+- ../ansible — configure resources after Terraform provisions them
+- ../azure — target cloud provisioned with the azurerm provider

package/skills/stacks/infra/vagrant/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: vagrant
+description: Vagrant is HashiCorp's tool for building and managing reproducible virtual machine development environments via a Vagrantfile; consult when configuring boxes, providers (VirtualBox/libvirt/Hyper-V), provisioners, synced folders, networking, or running vagrant up/ssh/destroy.
+domain: stack
+category: infra
+tags: [vagrant, hashicorp, virtualization, devops, infrastructure, vm, dev-environment]
+official_sources:
+  - https://developer.hashicorp.com/vagrant/docs
+  - https://github.com/hashicorp/vagrant
+  - https://developer.hashicorp.com/vagrant/install
+verified: 2026-06-17
+---
+
+# Vagrant
+
+## Overview
+Vagrant is HashiCorp's command-line tool for building and managing portable, reproducible virtual machine environments. A single `Vagrantfile` describes the box, provider, networking, and provisioning so any team member can run `vagrant up` to get an identical dev environment. Read this when configuring local VMs, defining provisioners, or scripting the VM lifecycle.
+
+## Official sources
+- Docs: https://developer.hashicorp.com/vagrant/docs
+- Repo: https://github.com/hashicorp/vagrant
+- Install: https://developer.hashicorp.com/vagrant/install
+
+## Install / setup
+```bash
+# macOS via Homebrew
+brew tap hashicorp/tap
+brew install hashicorp/tap/hashicorp-vagrant
+```
+Source: https://developer.hashicorp.com/vagrant/install
+
+## Core concepts
+- **Vagrantfile** — Ruby-based config (one per project) describing how to build and provision the VM.
+- **Box** — packaged base image (e.g. `hashicorp/bionic64`) used as the VM starting point.
+- **Provider** — virtualization backend that runs the VM (VirtualBox, libvirt, Hyper-V, VMware).
+- **Provisioner** — installs/configures software on `up` (shell, Ansible, Chef, Puppet, Docker).
+- **Synced folder** — host directory mounted into the guest (defaults to project dir at `/vagrant`).
+- **Box lifecycle** — `vagrant up` creates/boots, `ssh` connects, `halt` stops, `destroy` removes.
+- **Networking** — forwarded ports, private (host-only), or public (bridged) networks.
+- **Multi-machine** — define several VMs in one Vagrantfile via `config.vm.define`.
+
+## Best practices
+- Commit the `Vagrantfile` to version control so environments are reproducible (https://developer.hashicorp.com/vagrant/docs/vagrantfile).
+- Use provisioners to bake setup into the box rather than manual SSH steps (https://developer.hashicorp.com/vagrant/docs/provisioning).
+- Pin box versions to avoid unexpected base-image changes (https://developer.hashicorp.com/vagrant/docs/boxes/versioning).
+- Source boxes from the official Vagrant Cloud catalog (https://portal.cloud.hashicorp.com/vagrant/discover).
+- Keep provider-specific tweaks in a `config.vm.provider` block for portability (https://developer.hashicorp.com/vagrant/docs/providers).
+
+## Common pitfalls
+- `vagrant` not on PATH after install on Windows → log out and back in so PATH refreshes.
+- Slow or failing synced folders on VirtualBox → enable NFS or rsync for large codebases.
+- Stale VM state after Vagrantfile edits → run `vagrant reload --provision` to re-apply.
+
+## Examples
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "hashicorp/bionic64"
+  config.vm.network "forwarded_port", guest: 80, host: 8080
+  config.vm.provision "shell", inline: "apt-get update && apt-get install -y nginx"
+end
+```
+
+## Further reading
+- https://developer.hashicorp.com/vagrant/docs/vagrantfile — Vagrantfile reference
+- https://developer.hashicorp.com/vagrant/docs/provisioning — provisioners guide
+- https://portal.cloud.hashicorp.com/vagrant/discover — public box catalog
+
+## Related skills
+- ../ansible — provision Vagrant VMs with playbooks
+- ../terraform — provision real infrastructure beyond local VMs

package/skills/stacks/infra/vercel/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: vercel
+description: Managed hosting optimized for frontends and serverless functions; consult for deploys, preview URLs, env vars, and the Vercel CLI.
+domain: stack
+category: infra
+tags: [hosting, serverless, frontend, deploy, cli]
+official_sources:
+  - https://vercel.com/docs
+  - https://github.com/vercel/vercel
+verified: 2026-06-16
+---
+
+# Vercel
+
+## Overview
+Vercel is a managed platform for deploying frontend apps and serverless/edge functions, with Git-driven deployments and automatic preview URLs per branch/commit. It is optimized for frameworks like Next.js but supports any static or Node-based app. Read this when you need to deploy a web frontend, wire up preview environments, or script deploys via the CLI.
+
+## Official sources
+- Docs: https://vercel.com/docs
+- Repo: https://github.com/vercel/vercel
+- CLI install: https://vercel.com/docs/cli
+
+## Install / setup
+```bash
+npm i vercel
+```
+
+## Core concepts
+- Deployments: every push produces an immutable deployment with its own URL; production is a promoted deployment.
+- Preview deployments: non-production branches/commits get unique preview URLs for review before promotion.
+- Serverless & edge functions: backend logic runs as functions co-located with the deployment rather than a long-running server.
+- Environment variables: scoped per environment (development, preview, production) and pulled locally with `vercel pull`.
+- Projects & linking: a local directory is linked to a Vercel project so CLI commands target the right deployment target.
+- `vercel.json`: optional project configuration for routes, rewrites, headers, and cron jobs.
+
+## Best practices
+- Use `vercel build` then `vercel deploy --prebuilt` (or Git integration) so CI reproduces the same build the platform runs.
+- Store secrets as environment variables scoped to the correct environment, and use `vercel env pull` to sync them locally rather than committing them.
+- In CI/CD, authenticate with the `VERCEL_TOKEN` environment variable instead of passing `--token` on the command line (per the CLI docs) to keep tokens out of process lists/logs.
+- Promote a verified preview to production rather than deploying untested code straight to prod.
+
+## Common pitfalls
+- Assuming env vars set for production are available in preview/development → they are environment-scoped and must be added per environment.
+- Putting long-running or stateful work in serverless functions → they are short-lived and stateless; use a queue or external store.
+- Skipping `vercel link` → CLI commands may target the wrong or no project.
+
+## Examples
+```bash
+# Link the directory, pull env vars, and deploy to production
+vercel link
+vercel pull --environment=production
+vercel deploy --prod
+```
+
+## Further reading
+- https://vercel.com/docs/cli — full CLI command reference
+- https://vercel.com/docs/projects/environment-variables — environment variables
+
+## Related skills
+- ../netlify — comparable managed frontend hosting platform

package/skills/stacks/meta/astro/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: astro
+description: Content-focused web framework with an islands architecture — ships zero JS by default, supports React/Vue/Svelte; consult for content sites and blogs.
+domain: stack
+category: meta
+tags: [islands, content, ssg, ssr, ui-agnostic]
+official_sources:
+  - https://docs.astro.build/
+  - https://github.com/withastro/astro
+verified: 2026-06-16
+---
+
+# Astro
+
+## Overview
+Astro (by withastro) is "the web framework for content-driven websites" — a build tool whose islands architecture ships HTML with zero client-side JavaScript by default, hydrating only the interactive components ("islands") you opt in. It is UI-agnostic, integrating React, Vue, Svelte, and more. Read this when building content sites, blogs, or marketing pages, or reasoning about partial hydration.
+
+## Official sources
+- Docs: https://docs.astro.build/
+- Repo: https://github.com/withastro/astro
+- Install / setup: https://docs.astro.build/en/install-and-setup/
+
+## Install / setup
+```bash
+npm create astro@latest
+```
+
+## Core concepts
+- **Islands architecture.** Pages are mostly static HTML; interactive UI components are isolated "islands" that hydrate independently.
+- **Zero JS by default.** Components render to HTML at build/request time and ship no client JavaScript unless explicitly hydrated.
+- **`client:*` directives.** Directives like `client:load`, `client:idle`, and `client:visible` control whether and when an island hydrates on the client.
+- **UI-framework agnostic.** Astro components (`.astro`) coexist with React, Vue, Svelte, Solid, and others via integrations.
+- **Content collections.** Type-safe collections organize and query Markdown/MDX and other content for content-driven sites.
+- **Static or server output.** Astro can output a fully static site (SSG) or render on demand (SSR) via adapters.
+
+## Best practices
+- Keep most of the page as **static Astro components** and add interactivity only as islands, preserving the zero-JS default.
+- Choose the **least eager `client:*` directive** that meets the need (e.g. `client:visible`/`client:idle` over `client:load`) to minimize JS execution.
+- Use **content collections** for Markdown/MDX so content is type-checked and queryable rather than ad-hoc imports.
+- Run **Node.js v22.12.0 or higher**, as the official install docs require (odd-numbered versions like v23 are not supported).
+
+## Common pitfalls
+- Forgetting a `client:*` directive on an interactive component → it renders as static HTML and won't be interactive; add the appropriate directive.
+- Defaulting everything to `client:load` → over-hydrates the page and defeats Astro's performance model; pick a lazier directive.
+- Using an unsupported (odd-numbered) Node.js version → install Node v22.12.0+ as the docs require.
+
+## Examples
+```astro
+---
+// src/pages/index.astro
+import Counter from '../components/Counter.jsx';
+---
+<h1>Static heading, zero JS</h1>
+<Counter client:visible />
+```
+
+## Further reading
+- Islands architecture: https://docs.astro.build/en/concepts/islands/
+- Getting started: https://docs.astro.build/en/getting-started/
+
+## Related skills
+- ../nextjs — React meta-framework for full-stack apps
+- ../gatsby — alternative React static-site framework
+- ../vite — build tooling Astro builds upon

package/skills/stacks/meta/docusaurus/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: docusaurus
+description: Docusaurus is the React-based static site generator optimized for documentation sites and blogs; consult when scaffolding with create-docusaurus, editing docusaurus.config.js or sidebars.js, authoring MDX docs, versioning, i18n, or running `npm run start`.
+domain: stack
+category: meta
+tags: [docusaurus, ssg, static-site, react, mdx, documentation, blog]
+official_sources:
+  - https://docusaurus.io/docs
+  - https://github.com/facebook/docusaurus
+  - https://docusaurus.io/docs/installation
+verified: 2026-06-17
+---
+
+# Docusaurus
+
+## Overview
+Docusaurus (by Meta / the facebook org) is a static site generator that builds documentation websites and blogs as a React single-page app rendered to static HTML. It centers on MDX content, a `docs/` + `blog/` structure, versioning, and built-in i18n and search integrations. Read this when scaffolding a Docusaurus site, editing `docusaurus.config.js` or `sidebars.js`, authoring MDX, or configuring versioning and internationalization.
+
+## Official sources
+- Docs: https://docusaurus.io/docs
+- Repo: https://github.com/facebook/docusaurus
+- Install: https://docusaurus.io/docs/installation
+
+## Install / setup
+```bash
+npx create-docusaurus@latest my-website classic
+cd my-website
+npm run start
+```
+Commands from the official installation docs: https://docusaurus.io/docs/installation
+
+## Core concepts
+- **Classic preset** — `@docusaurus/preset-classic` bundles the docs, blog, pages, and theme/CSS; configured under `presets` in the config.
+- **`docusaurus.config.js`** — central site config (title, URL, presets, plugins, `themeConfig` for navbar/footer).
+- **MDX content** — docs and blog posts are MDX, mixing Markdown with imported React components.
+- **Sidebars** — `sidebars.js` defines the docs navigation tree (autogenerated from folders or hand-authored).
+- **Docs versioning** — `npm run docusaurus docs:version <v>` snapshots docs so multiple versions ship side by side.
+- **i18n** — built-in localization writes translations under `i18n/<locale>/` and builds per-locale sites.
+- **Pages & swizzling** — standalone React/MDX pages live in `src/pages/`; "swizzling" overrides theme components for customization.
+
+## Best practices
+- Use **`create-docusaurus@latest ... classic`** to scaffold so you start from the supported preset (https://docusaurus.io/docs/installation).
+- Pass `--typescript` to scaffold a typed config and components when you want TS (https://docusaurus.io/docs/installation).
+- Cut new doc versions with **`docs:version`** rather than copying folders, to keep the version dropdown consistent (https://docusaurus.io/docs/versioning).
+- Prefer **`--eject` swizzling sparingly** and favor `--wrap`, since wrapping survives upgrades better (https://docusaurus.io/docs/swizzling).
+
+## Common pitfalls
+- Broken internal links fail `npm run build` by default → fix the link or adjust `onBrokenLinks` in the config.
+- Heavy use of ejected (swizzled) theme components → upgrades break; prefer wrapping or theme config where possible.
+
+## Examples
+```js
+// docusaurus.config.js (excerpt)
+export default {
+  title: 'My Docs',
+  url: 'https://example.com',
+  baseUrl: '/',
+  presets: [
+    ['classic', { docs: { sidebarPath: './sidebars.js' }, blog: {} }],
+  ],
+};
+```
+
+## Further reading
+- https://docusaurus.io/docs/category/guides — feature guides (docs, blog, versioning, i18n)
+- https://docusaurus.io/docs/api/docusaurus-config — full config API reference
+
+## Related skills
+- ../astro — content framework with islands and partial hydration
+- ../nextjs — React meta-framework for full-stack apps
+- ../eleventy — JavaScript SSG with flexible template languages

package/skills/stacks/meta/eleventy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: eleventy
+description: Eleventy (11ty) is the zero-config JavaScript static site generator with pluggable template languages; consult when installing @11ty/eleventy, writing eleventy.config.js, using Nunjucks/Liquid/Markdown templates, collections, data cascade, or running `npx @11ty/eleventy --serve`.
+domain: stack
+category: meta
+tags: [eleventy, 11ty, ssg, static-site, javascript, nunjucks, markdown]
+official_sources:
+  - https://www.11ty.dev/docs/
+  - https://github.com/11ty/eleventy
+  - https://www.11ty.dev/docs/get-started/
+verified: 2026-06-17
+---
+
+# Eleventy (11ty)
+
+## Overview
+Eleventy (by the 11ty org) is a simpler, zero-config static site generator that runs on Node.js and transforms a directory of templates into HTML. It is template-language agnostic — Markdown, Nunjucks, Liquid, JavaScript, and more work out of the box — and avoids imposing a client-side framework. Read this when installing Eleventy, configuring `eleventy.config.js`, working with the data cascade, collections, or shortcodes, or running the dev server.
+
+## Official sources
+- Docs: https://www.11ty.dev/docs/
+- Repo: https://github.com/11ty/eleventy
+- Install: https://www.11ty.dev/docs/get-started/
+
+## Install / setup
+```bash
+npm install @11ty/eleventy
+npx @11ty/eleventy --serve
+```
+Commands from the official getting-started docs: https://www.11ty.dev/docs/
+
+## Core concepts
+- **Template languages** — many engines are supported per file extension (`.md`, `.njk`, `.liquid`, `.11ty.js`); pick freely or mix.
+- **Data cascade** — data merges from front matter, template/directory data files, global `_data/`, and computed data with a defined precedence.
+- **Collections** — tagged content is grouped into collections (`collections.post`) for listing, pagination, and navigation.
+- **Permalinks** — the `permalink` front-matter key controls each page's output path independent of the input path.
+- **Shortcodes & filters** — reusable functions added via config (`addShortcode`, `addFilter`) callable from any template language.
+- **Config file** — `eleventy.config.js` (or `.eleventy.js`) exports a function to register plugins, collections, passthrough copy, and input/output dirs.
+- **Passthrough copy** — `addPassthroughCopy` copies static assets (CSS, images) straight to the output untouched.
+
+## Best practices
+- Install Eleventy **locally** (devDependency) and run via `npx`, not globally, so versions are pinned per project (https://www.11ty.dev/docs/get-started/).
+- Configure passthrough copy and input/output directories in **`eleventy.config.js`** rather than CLI flags for reproducibility (https://www.11ty.dev/docs/config/).
+- Use the **data cascade** and `_data/` files for shared data instead of duplicating values in front matter (https://www.11ty.dev/docs/data-cascade/).
+- Prefer official plugins (e.g. **Image**, **RSS**, **Syntax Highlight**) over hand-rolled equivalents (https://www.11ty.dev/docs/plugins/).
+
+## Common pitfalls
+- Assets (CSS/images) missing from the build → register them with `addPassthroughCopy`; Eleventy only processes recognized template files by default.
+- Global install drift → install `@11ty/eleventy` as a project devDependency and invoke with `npx @11ty/eleventy`.
+
+## Examples
+```js
+// eleventy.config.js
+export default function (eleventyConfig) {
+  eleventyConfig.addPassthroughCopy("css");
+  eleventyConfig.addFilter("uppercase", (s) => String(s).toUpperCase());
+  return {
+    dir: { input: "src", output: "_site" },
+  };
+}
+```
+
+## Further reading
+- https://www.11ty.dev/docs/get-started/ — getting started walkthrough
+- https://www.11ty.dev/docs/data-cascade/ — data cascade reference
+
+## Related skills
+- ../astro — content framework with islands and partial hydration
+- ../hugo — Go SSG alternative with very fast builds
+- ../jekyll — Ruby SSG that powers GitHub Pages

package/skills/stacks/meta/gatsby/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: gatsby
+description: React-based static-site framework with a GraphQL data layer and plugin ecosystem; consult when building or maintaining a Gatsby site.
+domain: stack
+category: meta
+tags: [react, ssg, graphql, plugins, static-site]
+official_sources:
+  - https://www.gatsbyjs.com/docs/
+  - https://github.com/gatsbyjs/gatsby
+verified: 2026-06-16
+---
+
+# Gatsby
+
+## Overview
+Gatsby is a free, open-source, React-based framework "with performance, scalability, and security built in," used to build fast websites and apps. It pulls data from many sources into a unified GraphQL data layer and renders pages with React, with a large plugin ecosystem. Read this when building or maintaining a Gatsby site, especially content sites that aggregate data from CMSes, Markdown, or APIs.
+
+## Official sources
+- Docs: https://www.gatsbyjs.com/docs/
+- Repo: https://github.com/gatsbyjs/gatsby
+- Install / quick start: https://www.gatsbyjs.com/docs/quick-start/
+
+## Install / setup
+```bash
+npm init gatsby
+```
+
+## Core concepts
+- **React + GraphQL data layer.** Pages are React components that query a unified GraphQL layer aggregating data from many sources.
+- **Source and transformer plugins.** Plugins pull data in (CMS, filesystem, APIs) and transform it (e.g. Markdown → HTML) into the GraphQL layer.
+- **Pages.** Components in `src/pages` become routes automatically; pages can also be created programmatically in `gatsby-node`.
+- **Static generation.** Gatsby builds pages ahead of time for fast, secure static delivery (with additional rendering modes available).
+- **Configuration files.** `gatsby-config`, `gatsby-node`, `gatsby-browser`, and `gatsby-ssr` configure plugins, build-time APIs, and runtime hooks.
+
+## Best practices
+- Scaffold with **`npm init gatsby`** (optionally `npm init gatsby -- -y -ts my-site-name` for defaults + TypeScript) as the quick-start docs show.
+- Source and transform data through **plugins** rather than ad-hoc fetching so it flows into the GraphQL layer consistently.
+- Query data with **GraphQL** (page queries / `useStaticQuery`) to get exactly the data a component needs.
+- Note the quick start targets **intermediate-to-advanced developers**; beginners should start with the official tutorial first (per the docs).
+
+## Common pitfalls
+- Expecting `gatsby new` / `create-gatsby` → the current quick-start command is `npm init gatsby`.
+- Fetching data imperatively in components instead of via the GraphQL layer → use source/transformer plugins and GraphQL queries for build-time data.
+- Treating the quick start as a beginner path → it is aimed at intermediate/advanced users; use the tutorial to learn the fundamentals.
+
+## Examples
+```jsx
+// src/pages/index.js
+import * as React from "react"
+
+export default function Home() {
+  return <h1>Hello, Gatsby!</h1>
+}
+```
+
+## Further reading
+- Quick start: https://www.gatsbyjs.com/docs/quick-start/
+- Tutorial: https://www.gatsbyjs.com/docs/tutorial/
+
+## Related skills
+- ../nextjs — React framework with broader full-stack/SSR support
+- ../astro — content-focused islands framework
+- ../vite — modern build tooling for SPAs