ada-agent 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (339) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +256 -0
  3. package/bench/README.md +88 -0
  4. package/bench/swebench.mjs +242 -0
  5. package/bin/ada-server.mjs +6 -0
  6. package/bin/ada.mjs +7 -0
  7. package/docs/agent-loop.svg +66 -0
  8. package/docs/architecture.md +139 -0
  9. package/docs/architecture.svg +73 -0
  10. package/docs/connectors.md +48 -0
  11. package/docs/integrations.md +59 -0
  12. package/docs/login-flow.svg +56 -0
  13. package/docs/orchestration.md +45 -0
  14. package/package.json +64 -0
  15. package/skills/accessibility/SKILL.md +23 -0
  16. package/skills/add-logging/SKILL.md +23 -0
  17. package/skills/add-metrics/SKILL.md +23 -0
  18. package/skills/adr/SKILL.md +24 -0
  19. package/skills/aesthetic-direction/SKILL.md +24 -0
  20. package/skills/agent-loop/SKILL.md +23 -0
  21. package/skills/alerting/SKILL.md +23 -0
  22. package/skills/alpha-compositing/SKILL.md +23 -0
  23. package/skills/android-compose/SKILL.md +23 -0
  24. package/skills/angular-module/SKILL.md +23 -0
  25. package/skills/ansible-playbook/SKILL.md +24 -0
  26. package/skills/api-docs/SKILL.md +24 -0
  27. package/skills/app-store-prep/SKILL.md +23 -0
  28. package/skills/architecture-diagram/SKILL.md +21 -0
  29. package/skills/architecture-doc/SKILL.md +24 -0
  30. package/skills/audit-log/SKILL.md +23 -0
  31. package/skills/authz-review/SKILL.md +23 -0
  32. package/skills/aws-lambda/SKILL.md +24 -0
  33. package/skills/bash-script/SKILL.md +23 -0
  34. package/skills/batch/SKILL.md +23 -0
  35. package/skills/bisect/SKILL.md +23 -0
  36. package/skills/bounding-box/SKILL.md +24 -0
  37. package/skills/branch-cleanup/SKILL.md +23 -0
  38. package/skills/bundle-analyze/SKILL.md +23 -0
  39. package/skills/cache/SKILL.md +23 -0
  40. package/skills/call-graph/SKILL.md +23 -0
  41. package/skills/canvas-debug/SKILL.md +23 -0
  42. package/skills/cdn-setup/SKILL.md +23 -0
  43. package/skills/changelog/SKILL.md +24 -0
  44. package/skills/cherry-pick/SKILL.md +23 -0
  45. package/skills/ci-setup/SKILL.md +23 -0
  46. package/skills/cleanup/SKILL.md +23 -0
  47. package/skills/cli-tool/SKILL.md +23 -0
  48. package/skills/cloudformation/SKILL.md +23 -0
  49. package/skills/code-examples/SKILL.md +24 -0
  50. package/skills/code-review/SKILL.md +23 -0
  51. package/skills/color-palette/SKILL.md +24 -0
  52. package/skills/color-space/SKILL.md +24 -0
  53. package/skills/comment-why/SKILL.md +23 -0
  54. package/skills/commit/SKILL.md +26 -0
  55. package/skills/complexity-audit/SKILL.md +23 -0
  56. package/skills/component/SKILL.md +23 -0
  57. package/skills/component-library/SKILL.md +23 -0
  58. package/skills/connect-github/SKILL.md +20 -0
  59. package/skills/connect-mcp/SKILL.md +21 -0
  60. package/skills/connect-postgres/SKILL.md +20 -0
  61. package/skills/connect-remote/SKILL.md +23 -0
  62. package/skills/connect-slack/SKILL.md +20 -0
  63. package/skills/contract-audit/SKILL.md +25 -0
  64. package/skills/contributing/SKILL.md +23 -0
  65. package/skills/cpp-raii/SKILL.md +23 -0
  66. package/skills/cron-job/SKILL.md +23 -0
  67. package/skills/cv-preprocess/SKILL.md +24 -0
  68. package/skills/dark-mode/SKILL.md +24 -0
  69. package/skills/dashboard/SKILL.md +23 -0
  70. package/skills/dashboard-ui/SKILL.md +23 -0
  71. package/skills/data-export/SKILL.md +23 -0
  72. package/skills/data-validation/SKILL.md +23 -0
  73. package/skills/dataframe/SKILL.md +23 -0
  74. package/skills/db-index/SKILL.md +24 -0
  75. package/skills/dead-code/SKILL.md +23 -0
  76. package/skills/debug/SKILL.md +24 -0
  77. package/skills/deck-review/SKILL.md +24 -0
  78. package/skills/dedupe/SKILL.md +23 -0
  79. package/skills/dedupe-deps/SKILL.md +23 -0
  80. package/skills/dependency-audit/SKILL.md +23 -0
  81. package/skills/dependency-update/SKILL.md +23 -0
  82. package/skills/deploy/SKILL.md +23 -0
  83. package/skills/design-system/SKILL.md +24 -0
  84. package/skills/design-tokens/SKILL.md +24 -0
  85. package/skills/diagram-as-code/SKILL.md +24 -0
  86. package/skills/diff-explain/SKILL.md +23 -0
  87. package/skills/django-view/SKILL.md +23 -0
  88. package/skills/doc-lint/SKILL.md +24 -0
  89. package/skills/docker-compose/SKILL.md +23 -0
  90. package/skills/dockerize/SKILL.md +23 -0
  91. package/skills/docstrings/SKILL.md +23 -0
  92. package/skills/dotfiles/SKILL.md +23 -0
  93. package/skills/dpi-scaling/SKILL.md +23 -0
  94. package/skills/e2e-test/SKILL.md +23 -0
  95. package/skills/embeddings/SKILL.md +23 -0
  96. package/skills/empty-states/SKILL.md +23 -0
  97. package/skills/env-setup/SKILL.md +23 -0
  98. package/skills/erc20/SKILL.md +24 -0
  99. package/skills/error-tracking/SKILL.md +23 -0
  100. package/skills/estimate/SKILL.md +23 -0
  101. package/skills/etl-pipeline/SKILL.md +24 -0
  102. package/skills/eval-harness/SKILL.md +23 -0
  103. package/skills/exif-orientation/SKILL.md +23 -0
  104. package/skills/explain-code/SKILL.md +23 -0
  105. package/skills/express-middleware/SKILL.md +23 -0
  106. package/skills/extract-function/SKILL.md +23 -0
  107. package/skills/faq/SKILL.md +24 -0
  108. package/skills/fastapi-endpoint/SKILL.md +23 -0
  109. package/skills/favicon/SKILL.md +23 -0
  110. package/skills/feature-engineering/SKILL.md +23 -0
  111. package/skills/few-shot/SKILL.md +23 -0
  112. package/skills/find-owner/SKILL.md +23 -0
  113. package/skills/firmware-driver/SKILL.md +23 -0
  114. package/skills/fix-flaky-tests/SKILL.md +23 -0
  115. package/skills/flutter-widget/SKILL.md +23 -0
  116. package/skills/font-rendering/SKILL.md +23 -0
  117. package/skills/form-validation/SKILL.md +23 -0
  118. package/skills/format/SKILL.md +23 -0
  119. package/skills/game-loop/SKILL.md +23 -0
  120. package/skills/gas-optimize/SKILL.md +25 -0
  121. package/skills/gdpr-review/SKILL.md +24 -0
  122. package/skills/github-actions/SKILL.md +23 -0
  123. package/skills/glossary/SKILL.md +24 -0
  124. package/skills/go-idioms/SKILL.md +23 -0
  125. package/skills/gpu-profile/SKILL.md +23 -0
  126. package/skills/graphify/SKILL.md +21 -0
  127. package/skills/graphql-resolver/SKILL.md +23 -0
  128. package/skills/grpc-service/SKILL.md +23 -0
  129. package/skills/guardrails/SKILL.md +23 -0
  130. package/skills/healthcheck/SKILL.md +23 -0
  131. package/skills/heisenbug/SKILL.md +23 -0
  132. package/skills/helm-chart/SKILL.md +24 -0
  133. package/skills/hero-section/SKILL.md +23 -0
  134. package/skills/html-email/SKILL.md +24 -0
  135. package/skills/html-form/SKILL.md +23 -0
  136. package/skills/html-sanitize/SKILL.md +23 -0
  137. package/skills/html-table/SKILL.md +23 -0
  138. package/skills/html-to-pdf/SKILL.md +23 -0
  139. package/skills/http-client/SKILL.md +23 -0
  140. package/skills/i18n/SKILL.md +23 -0
  141. package/skills/i2c-spi/SKILL.md +23 -0
  142. package/skills/image-decode/SKILL.md +24 -0
  143. package/skills/image-memory/SKILL.md +24 -0
  144. package/skills/image-perf/SKILL.md +24 -0
  145. package/skills/image-pipeline/SKILL.md +24 -0
  146. package/skills/image-upload/SKILL.md +24 -0
  147. package/skills/infra-cost/SKILL.md +24 -0
  148. package/skills/input-validation/SKILL.md +23 -0
  149. package/skills/issue-template/SKILL.md +23 -0
  150. package/skills/java-streams/SKILL.md +23 -0
  151. package/skills/k8s-manifest/SKILL.md +23 -0
  152. package/skills/kotlin-coroutines/SKILL.md +23 -0
  153. package/skills/landing-page/SKILL.md +24 -0
  154. package/skills/laravel-controller/SKILL.md +23 -0
  155. package/skills/lazy-load/SKILL.md +23 -0
  156. package/skills/license-check/SKILL.md +23 -0
  157. package/skills/license-header/SKILL.md +23 -0
  158. package/skills/lint-fix/SKILL.md +23 -0
  159. package/skills/llm-cost/SKILL.md +23 -0
  160. package/skills/lockfile-fix/SKILL.md +23 -0
  161. package/skills/low-power/SKILL.md +23 -0
  162. package/skills/makefile/SKILL.md +23 -0
  163. package/skills/man-page/SKILL.md +24 -0
  164. package/skills/mcp-server/SKILL.md +23 -0
  165. package/skills/memory-leak/SKILL.md +23 -0
  166. package/skills/mermaid-diagram/SKILL.md +23 -0
  167. package/skills/meta-tags/SKILL.md +23 -0
  168. package/skills/micro-interactions/SKILL.md +23 -0
  169. package/skills/migration/SKILL.md +23 -0
  170. package/skills/migration-guide/SKILL.md +24 -0
  171. package/skills/mkdocs-setup/SKILL.md +24 -0
  172. package/skills/mobile-permissions/SKILL.md +23 -0
  173. package/skills/mock-api/SKILL.md +23 -0
  174. package/skills/modernize/SKILL.md +23 -0
  175. package/skills/monorepo-setup/SKILL.md +23 -0
  176. package/skills/motion-design/SKILL.md +23 -0
  177. package/skills/n-plus-one/SKILL.md +23 -0
  178. package/skills/naming-review/SKILL.md +23 -0
  179. package/skills/nextjs-route/SKILL.md +23 -0
  180. package/skills/nginx-config/SKILL.md +23 -0
  181. package/skills/ocr-debug/SKILL.md +24 -0
  182. package/skills/onboard/SKILL.md +23 -0
  183. package/skills/onboarding-map/SKILL.md +23 -0
  184. package/skills/open-pr/SKILL.md +24 -0
  185. package/skills/openapi/SKILL.md +23 -0
  186. package/skills/opencv-debug/SKILL.md +24 -0
  187. package/skills/orm-model/SKILL.md +23 -0
  188. package/skills/owasp-check/SKILL.md +24 -0
  189. package/skills/page-transitions/SKILL.md +23 -0
  190. package/skills/pagination/SKILL.md +23 -0
  191. package/skills/perf-optimize/SKILL.md +23 -0
  192. package/skills/perf-profile/SKILL.md +23 -0
  193. package/skills/physics/SKILL.md +23 -0
  194. package/skills/pitch-deck/SKILL.md +24 -0
  195. package/skills/pixel-diff/SKILL.md +23 -0
  196. package/skills/ponytail/SKILL.md +46 -0
  197. package/skills/postmortem/SKILL.md +24 -0
  198. package/skills/pptx-deck/SKILL.md +23 -0
  199. package/skills/pptx-export/SKILL.md +23 -0
  200. package/skills/pptx-from-markdown/SKILL.md +23 -0
  201. package/skills/pptx-template/SKILL.md +24 -0
  202. package/skills/pr-review/SKILL.md +24 -0
  203. package/skills/precommit/SKILL.md +23 -0
  204. package/skills/pricing-page/SKILL.md +23 -0
  205. package/skills/project-overview/SKILL.md +22 -0
  206. package/skills/prompt-template/SKILL.md +23 -0
  207. package/skills/property-test/SKILL.md +23 -0
  208. package/skills/protobuf/SKILL.md +23 -0
  209. package/skills/py-async/SKILL.md +23 -0
  210. package/skills/py-typing/SKILL.md +23 -0
  211. package/skills/query-optimize/SKILL.md +23 -0
  212. package/skills/rag-pipeline/SKILL.md +23 -0
  213. package/skills/rails-resource/SKILL.md +23 -0
  214. package/skills/rate-limit/SKILL.md +23 -0
  215. package/skills/react-hooks/SKILL.md +23 -0
  216. package/skills/react-native-screen/SKILL.md +23 -0
  217. package/skills/react-perf/SKILL.md +23 -0
  218. package/skills/readme/SKILL.md +24 -0
  219. package/skills/rebase/SKILL.md +24 -0
  220. package/skills/refactor/SKILL.md +23 -0
  221. package/skills/regression-test/SKILL.md +23 -0
  222. package/skills/release-notes/SKILL.md +24 -0
  223. package/skills/rename-symbol/SKILL.md +23 -0
  224. package/skills/repro/SKILL.md +23 -0
  225. package/skills/resolve-conflicts/SKILL.md +23 -0
  226. package/skills/responsive/SKILL.md +23 -0
  227. package/skills/rest-endpoint/SKILL.md +23 -0
  228. package/skills/retro/SKILL.md +23 -0
  229. package/skills/rtos-task/SKILL.md +23 -0
  230. package/skills/runbook/SKILL.md +25 -0
  231. package/skills/rust-borrow/SKILL.md +23 -0
  232. package/skills/rust-unsafe-audit/SKILL.md +23 -0
  233. package/skills/sanitize/SKILL.md +23 -0
  234. package/skills/schema-design/SKILL.md +23 -0
  235. package/skills/screenshot-debug/SKILL.md +22 -0
  236. package/skills/scroll-animation/SKILL.md +23 -0
  237. package/skills/secret-scan/SKILL.md +23 -0
  238. package/skills/security-audit/SKILL.md +23 -0
  239. package/skills/security-review/SKILL.md +23 -0
  240. package/skills/seed-data/SKILL.md +23 -0
  241. package/skills/self-review/SKILL.md +23 -0
  242. package/skills/semantic-html/SKILL.md +23 -0
  243. package/skills/semver-bump/SKILL.md +24 -0
  244. package/skills/shader/SKILL.md +23 -0
  245. package/skills/shader-debug/SKILL.md +23 -0
  246. package/skills/simplify-conditionals/SKILL.md +23 -0
  247. package/skills/sitemap/SKILL.md +23 -0
  248. package/skills/skeleton-loader/SKILL.md +23 -0
  249. package/skills/slide-charts/SKILL.md +24 -0
  250. package/skills/slide-outline/SKILL.md +23 -0
  251. package/skills/snapshot-update/SKILL.md +23 -0
  252. package/skills/solidity-contract/SKILL.md +25 -0
  253. package/skills/speaker-notes/SKILL.md +23 -0
  254. package/skills/spike/SKILL.md +23 -0
  255. package/skills/split-file/SKILL.md +23 -0
  256. package/skills/spring-controller/SKILL.md +23 -0
  257. package/skills/sprite-anim/SKILL.md +23 -0
  258. package/skills/sql-report/SKILL.md +23 -0
  259. package/skills/squash/SKILL.md +24 -0
  260. package/skills/ssl-setup/SKILL.md +23 -0
  261. package/skills/stacktrace/SKILL.md +23 -0
  262. package/skills/static-site/SKILL.md +24 -0
  263. package/skills/structured-logging/SKILL.md +23 -0
  264. package/skills/svelte-store/SKILL.md +23 -0
  265. package/skills/swiftui-view/SKILL.md +23 -0
  266. package/skills/tailwind-theme/SKILL.md +24 -0
  267. package/skills/tcp-server/SKILL.md +23 -0
  268. package/skills/tdd/SKILL.md +23 -0
  269. package/skills/terraform-module/SKILL.md +24 -0
  270. package/skills/test-coverage/SKILL.md +23 -0
  271. package/skills/texture-debug/SKILL.md +23 -0
  272. package/skills/threat-model/SKILL.md +23 -0
  273. package/skills/thumbnail/SKILL.md +24 -0
  274. package/skills/todo-scan/SKILL.md +23 -0
  275. package/skills/tool-definition/SKILL.md +23 -0
  276. package/skills/trace-flow/SKILL.md +23 -0
  277. package/skills/tracing/SKILL.md +23 -0
  278. package/skills/train-model/SKILL.md +24 -0
  279. package/skills/tree-shake/SKILL.md +23 -0
  280. package/skills/ts-generics/SKILL.md +23 -0
  281. package/skills/ts-strict/SKILL.md +23 -0
  282. package/skills/tui-app/SKILL.md +23 -0
  283. package/skills/tutorial/SKILL.md +24 -0
  284. package/skills/type-tighten/SKILL.md +23 -0
  285. package/skills/typography/SKILL.md +24 -0
  286. package/skills/ui-bug-repro/SKILL.md +23 -0
  287. package/skills/ui-polish/SKILL.md +24 -0
  288. package/skills/ui-review/SKILL.md +24 -0
  289. package/skills/vendor/SKILL.md +23 -0
  290. package/skills/visual-diff-ci/SKILL.md +24 -0
  291. package/skills/visual-regression/SKILL.md +23 -0
  292. package/skills/vue-composition/SKILL.md +23 -0
  293. package/skills/web-component/SKILL.md +23 -0
  294. package/skills/web-fonts/SKILL.md +24 -0
  295. package/skills/web3-frontend/SKILL.md +25 -0
  296. package/skills/webgl-debug/SKILL.md +23 -0
  297. package/skills/webhook/SKILL.md +23 -0
  298. package/skills/websocket/SKILL.md +23 -0
  299. package/skills/write-tests/SKILL.md +19 -0
  300. package/src/client/agent.ts +803 -0
  301. package/src/client/background.ts +39 -0
  302. package/src/client/checkpoint.ts +48 -0
  303. package/src/client/cli.ts +1253 -0
  304. package/src/client/compaction.ts +86 -0
  305. package/src/client/extensions.ts +83 -0
  306. package/src/client/hooks.ts +40 -0
  307. package/src/client/image.ts +26 -0
  308. package/src/client/lsp.ts +0 -0
  309. package/src/client/mcp.ts +276 -0
  310. package/src/client/models-dev.ts +52 -0
  311. package/src/client/pkg.ts +41 -0
  312. package/src/client/platform.ts +94 -0
  313. package/src/client/prompts.ts +47 -0
  314. package/src/client/render.ts +138 -0
  315. package/src/client/session.ts +107 -0
  316. package/src/client/settings.ts +86 -0
  317. package/src/client/skill-router.ts +79 -0
  318. package/src/client/skills.ts +199 -0
  319. package/src/client/snapshot.ts +56 -0
  320. package/src/client/telemetry.ts +24 -0
  321. package/src/client/todos.ts +23 -0
  322. package/src/client/tools.ts +756 -0
  323. package/src/client/tui-mode.ts +41 -0
  324. package/src/client/tui.ts +224 -0
  325. package/src/sdk/index.ts +36 -0
  326. package/src/selfcheck.ts +364 -0
  327. package/src/server/config.ts +58 -0
  328. package/src/server/credentials.ts +89 -0
  329. package/src/server/identity.ts +58 -0
  330. package/src/server/index.ts +113 -0
  331. package/src/server/oauth.ts +93 -0
  332. package/src/server/providers/adapter.ts +25 -0
  333. package/src/server/providers/anthropic.ts +189 -0
  334. package/src/server/providers/openai-compat.ts +76 -0
  335. package/src/server/providers/registry.ts +31 -0
  336. package/src/server/router.ts +29 -0
  337. package/src/server/sse.ts +20 -0
  338. package/src/shared/types.ts +20 -0
  339. package/tsconfig.json +15 -0
package/skills/dark-mode/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: dark-mode
3
+ description: Implement a polished dark mode via semantic tokens and prefers-color-scheme, not naive color inversion
4
+ category: ui-design
5
+ ---
6
+
7
+ # Dark Mode
8
+
9
+ Use this to add a dark theme that looks designed rather than inverted. Good dark mode is a parallel palette tuned for a dark substrate — it's not `filter: invert()`.
10
+
11
+ 1. Theme through semantic tokens only: components read `--bg`, `--surface`, `--text`, `--border`, `--accent`. Dark mode redefines those aliases; component CSS doesn't change.
12
+ 2. Avoid pure black (`#000`) backgrounds — use a very dark neutral (~oklch 0.18–0.22) so OLED smearing and harsh contrast soften, and so elevation can read.
13
+ 3. Signal elevation with lighter surfaces, not shadows: raised cards get a slightly lighter `--surface-raised`. Shadows mostly disappear on dark; lightness becomes the depth cue.
14
+ 4. Soften text: don't use `#fff` for body — drop to ~85–90% lightness to reduce halation, and re-check that muted text still clears 4.5:1 against the dark surface.
15
+ 5. Reduce accent chroma slightly and verify it on dark — saturated hues that pop on white can vibrate on dark; tune `--accent` and `--accent-fg` per theme.
16
+ 6. Wire it up: default to `@media (prefers-color-scheme: dark)`, allow a manual override via `[data-theme="dark"]` on `<html>`, persist the choice, and set `<meta name="color-scheme">` to avoid a white flash.
17
+ 7. Dim large imagery/illustration in dark (e.g. slightly lower brightness) and provide dark-tuned shadows/borders so nothing glows.
18
+
19
+ ## Rules
20
+ - Re-check contrast in dark independently — passing in light guarantees nothing.
21
+ - No pure `#000` background and no pure `#fff` text; both fatigue the eye.
22
+ - Convey depth with surface lightness, not drop shadows, in dark.
23
+ - Respect system preference by default, but let users override and persist it.
24
+ - Theme via token redefinition; never fork component styles per mode.
package/skills/dashboard/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dashboard
3
+ description: Build a Grafana/observability dashboard organized around the four golden signals
4
+ category: observability
5
+ ---
6
+
7
+ # Dashboard
8
+
9
+ Reach for this when you need an at-a-glance view of service health for triage during an incident or a daily glance.
10
+
11
+ 1. Decide the audience and scope (one service, one team, or fleet) and template it with variables (`$env`, `$service`, `$instance`) so one dashboard serves many targets.
12
+ 2. Lead with the four golden signals — traffic, errors, latency (p50/p95/p99), saturation — in the top row as the triage summary.
13
+ 3. Build panels from the queries that already back your alerts (rate, error ratio, latency histograms) so the dashboard and alerts agree.
14
+ 4. Order top-to-bottom from symptoms to causes: user-facing SLIs first, then dependencies (DB, queues, downstream), then resources (CPU, memory, connections).
15
+ 5. Set units, sane axis mins (0), and thresholds/annotations (deploys, incidents) so spikes are readable in context.
16
+ 6. Export the dashboard JSON and commit it to the repo so it's version-controlled and reproducible, not hand-edited in the UI.
17
+
18
+ ## Rules
19
+ - Keep it scannable — a dozen focused panels beat fifty; split deep-dives into linked dashboards.
20
+ - Use rate() over counters and quantiles over histograms; never plot raw counter totals.
21
+ - Make latency panels show percentiles, not just averages — averages hide tail pain.
22
+ - Template, don't duplicate: variables over per-host copies.
23
+ - Store dashboards as code (JSON/Jsonnet/Terraform) and review changes in PRs.
package/skills/dashboard-ui/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dashboard-ui
3
+ description: Design a clean, scannable data dashboard — clear hierarchy, restrained color, and fast comprehension.
4
+ category: ui-design
5
+ ---
6
+
7
+ # Dashboard UI
8
+
9
+ Reach for this when building an analytics or operations dashboard, where the job is to surface signal fast and let users act without hunting.
10
+
11
+ 1. Lead with the answer: a top row of 3–5 KPI stat cards (big number, label, trend delta with direction color), then supporting charts, then granular tables — most important, top-left.
12
+ 2. Lay out on a 12-column grid with consistent gutters and an 8px spacing rhythm; use container queries so cards reflow by their own width, not just the viewport.
13
+ 3. Keep the palette near-monochrome for chrome (neutral surfaces, one muted border token) and reserve saturated color strictly for data and semantic states (up/down, success/warn/error) so meaning pops.
14
+ 4. Set an information density that fits the user: align numbers right, use tabular figures (`font-variant-numeric: tabular-nums`), and tighten line-height in tables while keeping comfortable card padding.
15
+ 5. Make charts honest and minimal: drop chartjunk, label directly over legends where possible, start bar axes at zero, and cap each chart to one clear question.
16
+ 6. Provide structural states — loading skeletons matching card shapes, empty states with a next action, and persistent filters that don't reset on navigation.
17
+
18
+ ## Rules
19
+ - Color carries data meaning; never decorate the UI with the same hues you use for series, or users misread the charts.
20
+ - Whitespace is a feature — resist cramming; a scannable dashboard beats a complete-but-dense one.
21
+ - Use semantic green/red for trends but never rely on color alone — pair with arrows/signs for color-blind users (contrast ≥3:1).
22
+ - Numbers are the hero: tabular figures, right alignment, sensible rounding and units; no jittering digit widths.
23
+ - Keep the navigation/chrome quiet so the data is the brightest thing on screen.
package/skills/data-export/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: data-export
3
+ description: Export and transform database data to CSV or JSON safely and reproducibly
4
+ category: database
5
+ ---
6
+
7
+ # Data Export
8
+
9
+ Use when extracting query results or table contents into CSV/JSON for reporting, sharing, backups, or feeding another system.
10
+
11
+ 1. Define exactly what to export: the query or table, the columns, and the row scope (filters, date range) — avoid dumping more than needed.
12
+ 2. Stream or paginate large result sets rather than loading everything into memory at once.
13
+ 3. Serialize with a real CSV/JSON library so quoting, escaping, delimiters, encoding (UTF-8), and nulls are handled correctly — don't hand-concatenate strings.
14
+ 4. Normalize types on the way out: format timestamps to ISO 8601, fix numeric precision, and encode nulls/booleans consistently.
15
+ 5. Redact or omit sensitive fields (PII, secrets, tokens) and confirm the destination of the file is appropriate for its sensitivity.
16
+ 6. Verify the output: row count matches the query, a sample re-imports cleanly, and the file opens in the target tool.
17
+
18
+ ## Rules
19
+ - Never build CSV/JSON by string concatenation — embedded commas, quotes, and newlines will corrupt it.
20
+ - Stream large exports; loading millions of rows into memory will OOM the process.
21
+ - Always emit UTF-8 and be explicit about delimiter and quoting so downstream tools parse it.
22
+ - Scrub sensitive columns before export and never write secrets to a shared or world-readable file.
23
+ - Make exports reproducible: deterministic ordering (`ORDER BY`) and a recorded query, so the same inputs yield the same file.
package/skills/data-validation/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: data-validation
3
+ description: Add data-quality and schema checks that fail fast on bad data
4
+ category: data-ml
5
+ ---
6
+
7
+ # Data Validation
8
+
9
+ Use when data enters a pipeline, a model, or a report and you need to catch schema drift, nulls, and out-of-range values before they cause silent corruption downstream.
10
+
11
+ 1. Define the expected schema: column names, types, nullability, and allowed value ranges or sets.
12
+ 2. Add structural checks (required columns present, types correct, primary key unique and non-null) at ingestion.
13
+ 3. Add content checks: null rates within tolerance, numeric ranges, categorical domains, referential integrity, and freshness/row-count bounds.
14
+ 4. Decide per-check severity — hard-fail and stop the pipeline, or warn and quarantine bad rows to a dead-letter table.
15
+ 5. Wire checks into the pipeline as a gate before the load/train step, with clear error messages naming the failing column and rule.
16
+ 6. Track validation results over time so gradual drift (rising null rate, shifting distribution) is visible, not just hard breaks.
17
+
18
+ ## Rules
19
+ - Fail fast at the boundary; bad data is cheapest to catch before it's joined, aggregated, or trained on.
20
+ - Make failures specific — name the column, the rule, and example offending values, not just "validation failed".
21
+ - Separate hard failures from warnings; not every anomaly should halt the whole run.
22
+ - Check the unglamorous invariants too: row counts, freshness, and key uniqueness catch the most real incidents.
23
+ - Keep expectations versioned next to the data contract so schema changes are reviewed deliberately.
package/skills/dataframe/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dataframe
3
+ description: Transform tabular data with pandas or polars cleanly and reproducibly
4
+ category: data-ml
5
+ ---
6
+
7
+ # Dataframe
8
+
9
+ Use when wrangling tabular data — cleaning, reshaping, joining, aggregating — with pandas or polars, and you want correct, readable, vectorized code.
10
+
11
+ 1. Load with explicit dtypes (and parse dates) so columns don't silently become object/float; check `df.dtypes` and shape first.
12
+ 2. Inspect before transforming: nulls per column, value ranges, duplicates, and cardinality of key columns.
13
+ 3. Build the transform as a chain of vectorized ops (filter, assign/with_columns, groupby/agg, merge/join) — avoid `iterrows`/Python loops.
14
+ 4. Be explicit about join keys and `how`; verify row count after each join to catch fan-out from non-unique keys.
15
+ 5. Handle missing data deliberately (drop, fill, or flag) rather than letting NaN propagate into aggregates.
16
+ 6. Validate the output shape, dtypes, and a few known values before writing; persist to a columnar format (Parquet) when possible.
17
+
18
+ ## Rules
19
+ - Prefer vectorized/expression APIs over `apply` with Python functions; reach for `apply` only as a last resort.
20
+ - Avoid chained-assignment on slices in pandas (use `.loc`); in polars build new frames with expressions.
21
+ - Always validate row counts around joins and groupbys — silent fan-out and dropped rows are the top bugs.
22
+ - Set dtypes at read time; don't rely on inference for ids, categoricals, or money.
23
+ - Keep transforms as a pure function of the input frame so the same input always yields the same output.
package/skills/db-index/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: db-index
3
+ description: Add the right database indexes for slow queries using EXPLAIN, not guesswork
4
+ category: performance
5
+ ---
6
+
7
+ # DB Index
8
+
9
+ Reach for this when a query is slow because the database scans far more rows than it returns.
10
+
11
+ 1. Identify the slow query from logs/APM and run `EXPLAIN ANALYZE` (or the engine's equivalent) to see the plan and row counts.
12
+ 2. Look for sequential/full scans, high "rows examined vs rows returned" ratios, and filesorts on large tables.
13
+ 3. Index the columns in `WHERE`, `JOIN`, and `ORDER BY`; build a composite index in the order equality-first, then range, then sort.
14
+ 4. Create the index concurrently/online on production (`CREATE INDEX CONCURRENTLY`, or online DDL) to avoid locking the table.
15
+ 5. Re-run `EXPLAIN ANALYZE` and confirm the planner uses the new index and rows-examined drops.
16
+ 6. Verify write-path cost is acceptable — each index slows inserts/updates, so drop indexes that don't earn their keep.
17
+
18
+ ## Rules
19
+ - Always read the query plan before and after — never add an index on a hunch.
20
+ - Composite index column order matters: leftmost prefix must match the query's filter/sort.
21
+ - Prefer covering indexes (include selected columns) to avoid heap lookups on hot reads.
22
+ - High-cardinality columns benefit most; indexing a low-cardinality boolean rarely helps.
23
+ - Build large indexes concurrently/online and off-peak to avoid blocking writes.
24
+ - More indexes is not better — they bloat storage and slow every write; remove unused ones.
package/skills/dead-code/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dead-code
3
+ description: Find and remove unused code, exports, and files across the project
4
+ category: review
5
+ ---
6
+
7
+ # Dead Code
8
+
9
+ Use this to clean out code that nothing references anymore — unreachable branches, unused exports, orphaned files, and stale dependencies that quietly accrue.
10
+
11
+ 1. Run the language's dead-code tooling first (e.g. `ts-prune`/`knip`, `unimport`, `vulture`, `cargo +nightly udeps`, compiler `-Wunused`, or IDE "unused" inspections).
12
+ 2. For each candidate, grep the whole repo for the symbol — including dynamic references, string-based lookups, reflection, and test-only usage — before deleting.
13
+ 3. Remove unreachable branches, commented-out blocks, unused params, and exports no longer imported anywhere.
14
+ 4. Delete orphaned files and prune dependencies in the manifest that nothing imports.
15
+ 5. Run the build, type-checker, and full test suite after each batch of deletions to confirm nothing broke.
16
+ 6. Commit the removals in a focused, behavior-preserving commit separate from any feature work.
17
+
18
+ ## Rules
19
+ - Verify a symbol is truly unreferenced before deleting — dynamic dispatch, DI containers, and string keys evade static analysis.
20
+ - Keep public API surface intact unless you've confirmed no external consumer depends on it; deprecate before deleting when unsure.
21
+ - Don't delete code guarded by feature flags, platform conditionals, or build targets you're not exercising.
22
+ - Make deletions in small, reviewable commits so a regression is easy to bisect and revert.
23
+ - Tests and fixtures count as usage — don't delete code only the tests use unless you're removing the tests too.
package/skills/debug/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: debug
3
+ description: Apply a systematic debugging procedure — reproduce, isolate, fix, verify — instead of guessing at fixes
4
+ category: debugging
5
+ ---
6
+
7
+ # Debug
8
+
9
+ Reach for this when something is broken or behaving unexpectedly and you're tempted to start changing code. Slow down and follow the loop so the fix is real, not a coincidence.
10
+
11
+ 1. State the bug precisely: what you expected, what actually happened, and the exact error or wrong output.
12
+ 2. Reproduce it reliably — get a single command or steps that fail every time. If you can't reproduce it, you can't fix it.
13
+ 3. Form one hypothesis about the cause and predict what you'd observe if it were true.
14
+ 4. Isolate: bisect the input, the code path, or git history (`git bisect`) until the failure is localized to a few lines.
15
+ 5. Confirm the root cause by observation (a log, a breakpoint, a value) — not by assumption.
16
+ 6. Apply the smallest fix that addresses the cause, then re-run the repro to confirm it now passes.
17
+ 7. Add or adjust a test that would have caught this, and check nearby code for the same mistake.
18
+
19
+ ## Rules
20
+ - Change one thing at a time; if you change three, you won't know which fixed it.
21
+ - Fix the cause, not the symptom — suppressing an error or adding a null guard at the crash site is rarely the real fix.
22
+ - Never claim it's fixed without re-running the exact reproduction that failed.
23
+ - If a hypothesis is disproven, discard it and write a new one — don't keep patching a dead theory.
24
+ - Keep a running note of what you ruled out so you don't loop back over it.
package/skills/deck-review/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: deck-review
3
+ description: Review a slide deck for clarity, narrative flow, and per-slide density; return concrete fixes.
4
+ category: pptx
5
+ ---
6
+
7
+ # Deck Review
8
+
9
+ Use when a draft deck exists and needs a critical pass before it ships — checking message, story arc, and overload, not just typos.
10
+
11
+ 1. Read the whole deck once for the overall argument: is there a single clear thesis and does the order build to it?
12
+ 2. Check each slide for one idea — flag any slide doing two jobs and any headline that's a topic label instead of a takeaway.
13
+ 3. Measure density: flag slides over ~6 bullets, walls of text, tiny fonts (<18pt body), or more than one chart competing for attention.
14
+ 4. Test the flow: do consecutive slides connect, are there gaps or redundant slides, does the close state a clear next step?
15
+ 5. Audit visuals and data: unlabeled charts, missing units, inconsistent fonts/colors, distorted images, unsourced claims.
16
+ 6. Return a slide-by-slide list of specific issues plus prioritized fixes (cut / split / rewrite headline / add data), and offer to apply them.
17
+
18
+ ## Rules
19
+ - Give actionable per-slide notes, not vague praise ("split slide 7", not "tighten this up").
20
+ - Enforce one idea per slide and assertion-style headlines throughout.
21
+ - Prefer cutting and splitting over adding; most weak decks have too much, not too little.
22
+ - Check consistency of fonts, colors, and capitalization across all slides.
23
+ - Verify the deck ends with a clear ask or takeaway, not a bare "Thank you".
24
+ - Distinguish must-fix (breaks the message) from nice-to-have polish.
package/skills/dedupe/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dedupe
3
+ description: Collapse duplicated logic into a single shared implementation
4
+ category: refactoring
5
+ ---
6
+
7
+ # Dedupe
8
+
9
+ Use when the same logic appears in two or more places and they must stay in sync. Unify only genuine duplication, not code that merely looks similar.
10
+
11
+ 1. Locate all copies and diff them carefully to find the real differences (params, edge cases, ordering).
12
+ 2. Confirm the duplicates represent the same concept — if they drift for different reasons, leave them apart.
13
+ 3. Extract the shared core into one function/module; express the differences as parameters or hooks.
14
+ 4. Replace each copy with a call to the shared implementation.
15
+ 5. Run tests across every former call site, including the edge cases each copy handled.
16
+ 6. Commit, and note any intentional remaining near-duplicates and why.
17
+
18
+ ## Rules
19
+ - Don't force unification when the only commonality is shape — premature abstraction is worse than duplication (WET beats a wrong DRY).
20
+ - If copies differ subtly, decide deliberately which behavior is correct; merging can silently pick one and change the other.
21
+ - Keep the shared abstraction at the right layer so callers don't gain an awkward dependency.
22
+ - Avoid a parameter explosion; if the unified function needs many flags to cover variants, the abstraction is wrong.
23
+ - Verify each original edge case still works after merging — that's where dedupe bugs hide.
package/skills/dedupe-deps/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dedupe-deps
3
+ description: Remove duplicate and unused dependencies to shrink install size and the dependency tree
4
+ category: dependencies
5
+ ---
6
+
7
+ # Dedupe Deps
8
+
9
+ Use when the dependency tree has bloated — duplicate versions of the same package, or declared deps nothing imports.
10
+
11
+ 1. Flatten duplicate versions where the manager allows it (`npm dedupe`, `pnpm dedupe`, `yarn dedupe`) and inspect the resulting tree.
12
+ 2. Find unused declared deps with a tool (`depcheck`, `knip`, `cargo-udeps`, `pip-autoremove --dry-run`) and cross-check each hit by grepping imports.
13
+ 3. Confirm anything flagged isn't used only at runtime, in config, in scripts, or by a build/CI step before removing it.
14
+ 4. Move build-only and test-only packages into devDependencies (or the equivalent) so production installs stay lean.
15
+ 5. Remove the confirmed-dead entries, regenerate the lockfile, and reinstall clean.
16
+ 6. Run the full test suite and a production build to prove nothing relied on the removed packages.
17
+
18
+ ## Rules
19
+ - Treat automated "unused" reports as suspects, not verdicts — verify each before deleting.
20
+ - Watch for deps referenced only in strings, config files, CLI scripts, or dynamic imports that scanners miss.
21
+ - Distinguish a genuinely unused dep from a duplicated version; they need different fixes.
22
+ - Don't delete a transitive dep directly — remove the top-level package that pulls it in.
23
+ - Re-run the build after deduping; flattening can surface a peer-dependency conflict.
package/skills/dependency-audit/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dependency-audit
3
+ description: Run npm/pip/etc audit, triage advisories, and apply the safest upgrades
4
+ category: security
5
+ ---
6
+
7
+ # Dependency Audit
8
+
9
+ Use this to find and triage known-vulnerable third-party packages in a project's dependency tree.
10
+
11
+ 1. Run the ecosystem auditor: `npm audit --json`, `pip-audit`, `pnpm audit`, `cargo audit`, or `osv-scanner -r .`; capture the raw output.
12
+ 2. For each advisory note severity, whether it is a direct or transitive dependency, and if a fixed version exists.
13
+ 3. Confirm reachability: check whether the vulnerable code path is actually called by this project — a CVE in an unused code path is lower priority.
14
+ 4. Fix direct deps by bumping to the patched version; for transitive ones use overrides/resolutions (`overrides` in package.json, constraints file for pip) or upgrade the parent.
15
+ 5. Re-run the auditor and the test suite to confirm the advisory clears and nothing broke.
16
+ 6. Record any advisory you intentionally accept (no fix available, not reachable) with a dated justification.
17
+
18
+ ## Rules
19
+ - Prioritize by severity AND reachability/exploitability, not by raw count of advisories.
20
+ - Pin to the minimal version that fixes the issue; avoid sweeping major-version bumps in the same change.
21
+ - Lockfiles must be regenerated and committed so the fix is reproducible.
22
+ - Beware audit noise: dev-only/build-time deps rarely warrant a risky upgrade — judge by where the package runs.
23
+ - Add the audit to CI (failing on high/critical) so regressions are caught automatically.
package/skills/dependency-update/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dependency-update
3
+ description: Bump dependencies safely, regenerate the lockfile, and confirm the test suite still passes
4
+ category: dependencies
5
+ ---
6
+
7
+ # Dependency Update
8
+
9
+ Reach for this when bumping one or many dependencies and you want to land the change without breaking the build.
10
+
11
+ 1. Snapshot the current state: note the green test/build baseline and capture the manifest + lockfile in git so you can diff later.
12
+ 2. List what is outdated (`npm outdated`, `pip list --outdated`, `cargo update --dry-run`) and separate patch/minor from major bumps.
13
+ 3. Bump in small batches — patches and minors first, one risky major at a time — and regenerate the lockfile deterministically.
14
+ 4. Read the changelog/release notes for any major bump and apply required code or config migrations.
15
+ 5. Run install clean (`npm ci`, `pip install -r` in a fresh venv) plus the full test suite and a build.
16
+ 6. Commit the manifest and lockfile together with a message naming the packages and version ranges.
17
+
18
+ ## Rules
19
+ - Never edit the lockfile by hand — let the package manager regenerate it.
20
+ - Pin majors and review them individually; a batched major bump hides which one broke things.
21
+ - Run a clean install, not an incremental one, so a stale cache doesn't mask a resolution problem.
22
+ - If tests fail, bisect the batch rather than reverting everything; isolate the offending package.
23
+ - Keep manifest and lockfile changes in the same commit so CI never sees a drifted pair.
package/skills/deploy/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: deploy
3
+ description: Write a repeatable deployment script or checklist that ships the app safely with a rollback path
4
+ category: ci-cd
5
+ ---
6
+
7
+ # Deploy
8
+
9
+ Reach for this when shipping to an environment needs to be repeatable, reviewable, and recoverable instead of ad-hoc.
10
+
11
+ 1. Establish prerequisites: required env vars/secrets present, target reachable, correct branch/tag, clean working tree.
12
+ 2. Run the gate before shipping — build the release artifact and run tests/lint; abort the script on any failure (`set -euo pipefail`).
13
+ 3. Capture the current version/revision so you have a concrete rollback target.
14
+ 4. Deploy the artifact (push image, run migrations, restart/switch traffic) in a defined order, migrations before code that needs them.
15
+ 5. Verify post-deploy: hit the healthcheck and a smoke endpoint; fail the deploy if they don't pass.
16
+ 6. Document rollback (redeploy the captured previous version) and announce success only after verification passes.
17
+
18
+ ## Rules
19
+ - Make the script idempotent and fail-fast (`set -euo pipefail`); a half-run deploy must not look successful.
20
+ - Always record the prior version before changing anything so rollback is one command.
21
+ - Run DB migrations in their own step with a tested down/rollback path.
22
+ - Never hardcode secrets in the script — read them from the environment or a secret store.
23
+ - Gate "done" on a real healthcheck/smoke test, not just "the command exited 0".
package/skills/design-system/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: design-system
3
+ description: Build a cohesive design system from tokens up to components, with one source of truth and zero magic numbers
4
+ category: ui-design
5
+ ---
6
+
7
+ # Design System
8
+
9
+ Reach for this when a UI has grown inconsistent — drifting spacings, one-off colors, copy-pasted buttons — or when starting a product that needs to scale past a few screens.
10
+
11
+ 1. Audit what exists: screenshot every surface, list every distinct color, font size, radius, shadow, and spacing in use. The sprawl you find is the problem statement.
12
+ 2. Define the token layer first (see the design-tokens skill): primitives (`--blue-500`), then semantic aliases (`--color-accent`, `--bg-surface`, `--text-muted`). Components reference semantics only, never primitives.
13
+ 3. Lock the foundations: a modular type scale (1.2–1.25 ratio), a 4px spacing base, a radius set (sm/md/lg/full), and 2–3 elevation shadows. Everything downstream composes from these.
14
+ 4. Build primitives as composable components: Button (variant × size × state), Input, Card, Badge. Encode every visual decision as a token, so a theme swap is a token swap.
15
+ 5. Codify states explicitly — default, hover, focus-visible, active, disabled, loading. A system that only specifies the resting state isn't a system.
16
+ 6. Document usage with live examples and do/don't pairs (Storybook or an MDX page). A token nobody knows about gets bypassed.
17
+ 7. Ship with lint guardrails: reject raw hex and arbitrary px in PRs so drift can't creep back in.
18
+
19
+ ## Rules
20
+ - One source of truth: a value lives in exactly one token; if you typed a hex or px in a component, it's a bug.
21
+ - Two-tier tokens always — primitive then semantic — so re-theming touches the alias layer only.
22
+ - Name by role, not by look: `--color-danger`, not `--color-red` (red may become orange later).
23
+ - Every interactive component must define focus-visible and disabled, not just hover.
24
+ - Prefer composition over variant explosion; if a component has 12 boolean props, split it.
package/skills/design-tokens/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: design-tokens
3
+ description: Define color, space, type, radius, and shadow tokens as layered CSS custom properties with semantic roles
4
+ category: ui-design
5
+ ---
6
+
7
+ # Design Tokens
8
+
9
+ Use this to turn scattered hardcoded values into a small, principled set of variables that every component reads from — the foundation under any design system or theme.
10
+
11
+ 1. Split into two tiers: a primitive scale (`--gray-50`…`--gray-950`, `--blue-500`) that names raw values, and a semantic layer (`--bg`, `--surface`, `--text`, `--border`, `--accent`) that maps roles onto primitives.
12
+ 2. Build space on a 4px base as a scale, not ad-hoc: `--space-1: 4px` … `--space-8: 32px`. Components only ever use scale steps, killing 13px and 27px outliers.
13
+ 3. Define type tokens from a ratio (see typography): `--text-sm/base/lg/xl/2xl` plus `--leading-tight/normal/relaxed` and `--tracking-tight`. Pair each size with a sensible line-height.
14
+ 4. Standardize radius (`--radius-sm/md/lg/full`) and elevation (`--shadow-sm/md/lg`) as layered, low-alpha shadows — never a single harsh `0 2px 4px #000`.
15
+ 5. Express color in `oklch()` for perceptually even ramps and easy lightness flips; provide `--color-*` semantic aliases so dark mode redefines the alias, not the component.
16
+ 6. Scope tokens to `:root`, override per-theme via `[data-theme]` or `@media (prefers-color-scheme)`, and expose only semantic tokens to component code.
17
+ 7. Generate platform outputs (CSS vars, Tailwind config, JSON) from one source file (e.g. Style Dictionary) so web and native never diverge.
18
+
19
+ ## Rules
20
+ - Components consume semantic tokens only; primitives are private implementation detail.
21
+ - No naked values in component CSS — every color, space, radius, and shadow is a `var(--…)`.
22
+ - Name tokens by purpose (`--text-muted`) not appearance (`--gray-400`).
23
+ - Keep each scale short (5–9 steps); an infinite ramp invites inconsistency.
24
+ - Use `oklch()`/`hsl()` over hex so you can derive hover/active states by nudging lightness.
package/skills/diagram-as-code/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: diagram-as-code
3
+ description: Author architecture diagrams as code (PlantUML, D2, or Graphviz) and render them to SVG in the build.
4
+ category: docs
5
+ ---
6
+
7
+ # Diagram As Code
8
+
9
+ Use when diagrams must be version-controlled, reviewed in PRs, and regenerated deterministically — pick this over hand-drawn tools for anything that outlives a single meeting.
10
+
11
+ 1. Choose the tool: D2 for modern layout and clean syntax, PlantUML for rich UML (class/component/sequence), Graphviz/DOT for graph-theoretic or auto-laid-out graphs.
12
+ 2. Put the source in the repo next to the doc (`diagrams/auth.d2`, `*.puml`, `*.dot`) — text in, image out.
13
+ 3. Write the diagram, naming nodes by their real system role and grouping with containers/clusters/packages.
14
+ 4. Render to SVG (vector, scalable, diffable-ish): `d2 auth.d2 auth.svg`, `plantuml -tsvg arch.puml`, or `dot -Tsvg graph.dot -o graph.svg`.
15
+ 5. Reference the rendered SVG from Markdown; commit both source and output, or generate output in CI.
16
+ 6. Add a make target / npm script (`make diagrams`) so anyone can regenerate all images with one command.
17
+ 7. Re-render and review the visual diff whenever the source changes; never edit the SVG by hand.
18
+
19
+ ## Rules
20
+ - Source of truth is the `.d2`/`.puml`/`.dot` file — the SVG is a build artifact.
21
+ - Prefer SVG over PNG: crisp at any zoom, smaller, and partly readable in diffs.
22
+ - Pin the renderer version (container image or lockfile) so layout stays stable across machines.
23
+ - Let the layout engine place nodes; only nudge with constraints when the auto-layout is genuinely wrong.
24
+ - Keep one diagram per file so renders and reviews stay focused.
package/skills/diff-explain/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: diff-explain
3
+ description: Explain what a diff changes and why, summarizing intent, behavior shifts, and risks for a reviewer
4
+ category: code-understanding
5
+ ---
6
+
7
+ # Diff Explain
8
+
9
+ Use to summarize a commit, PR, or working diff for a reviewer — what changed, why, and what to watch for — without restating every line.
10
+
11
+ 1. Get the diff and its context: `git diff`, `git show <ref>`, or `gh pr diff`, plus the commit message or PR description for stated intent.
12
+ 2. Group the hunks by purpose (feature, refactor, fix, test, config) rather than walking files top to bottom.
13
+ 3. For each group, state the behavior change — what the code does differently now, not which lines moved.
14
+ 4. Separate functional changes from no-op churn (renames, formatting, moves) so reviewers focus on what matters.
15
+ 5. Identify risks: edge cases, removed checks, changed defaults, API/signature changes, and missing or weakened tests.
16
+ 6. Summarize as intent + behavior delta + risks, and note whether the diff matches its stated purpose.
17
+
18
+ ## Rules
19
+ - Explain effect, not mechanics — "now rejects empty input" beats "added an if on line 40".
20
+ - Flag scope creep: changes unrelated to the stated intent deserve a callout.
21
+ - Pay attention to deletions and weakened conditions; removed guards are easy to miss and often the bug.
22
+ - Note untested behavior changes and any public-interface or migration impact explicitly.
23
+ - If the diff's intent is unclear from the code and message, say so rather than inventing a rationale.
package/skills/django-view/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: django-view
3
+ description: Add a Django view with its URL route and template
4
+ category: frameworks
5
+ ---
6
+
7
+ # Django View
8
+
9
+ Use to add a new page or endpoint to a Django app — wiring a view, a URL pattern, and (for HTML) a template.
10
+
11
+ 1. Write the view in the app's `views.py`: a function view taking `request` or a class-based view (e.g. `ListView`), returning `render(request, template, context)` or a `JsonResponse`.
12
+ 2. Add a URL pattern in the app's `urls.py` with a `name=`, then `include()` that app's urls from the project `urls.py` if not already.
13
+ 3. For HTML, create the template under `<app>/templates/<app>/<name>.html` and render context variables.
14
+ 4. Query data via the ORM in the view; pass only what the template needs in `context`.
15
+ 5. Reverse URLs with `{% url 'app:name' %}` / `reverse()` rather than hardcoding paths.
16
+ 6. Run `python manage.py runserver`, hit the URL, and confirm the response and template render.
17
+
18
+ ## Rules
19
+ - Namespace URLs with `app_name` in the app's `urls.py` and reference them as `'app:name'`.
20
+ - Keep business logic in models/services, not fat views; views orchestrate request → response.
21
+ - Protect mutating views with CSRF (forms) and the right method guards (`require_POST`, `LoginRequiredMixin`).
22
+ - Use `get_object_or_404` instead of bare `.get()` to avoid unhandled `DoesNotExist`.
23
+ - Don't put queries in templates; resolve them in the view and watch for N+1 (use `select_related`/`prefetch_related`).
package/skills/doc-lint/SKILL.md ADDED
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: doc-lint
3
+ description: Lint docs in CI for broken links, spelling, and style so prose breakage fails the build like code does.
4
+ category: docs
5
+ ---
6
+
7
+ # Doc Lint
8
+
9
+ Use when docs are drifting — dead links, typos, inconsistent style — and you want automated gates instead of manual proofreading.
10
+
11
+ 1. Link-check: run `lychee` (or `markdown-link-check`) across the docs tree to catch dead internal and external URLs.
12
+ 2. Spell-check with a project dictionary: `cspell` with a committed `cspell.json` allow-list for domain terms.
13
+ 3. Style/lint Markdown with `markdownlint` (or Vale for prose style rules like passive voice, weasel words, heading case).
14
+ 4. Add a config to silence intentional exceptions (ignore patterns, allowed words) — keep it in-repo, not in flags.
15
+ 5. Wire all three into CI as a `docs-lint` job that fails the PR on new violations.
16
+ 6. Run the same commands locally / in a pre-commit hook so authors catch issues before pushing.
17
+ 7. Triage existing noise once with a baseline, then enforce zero-new-violations going forward.
18
+
19
+ ## Rules
20
+ - Make link-checking non-blocking-on-flakes: cache, retry, and allow-list known-flaky external hosts so CI isn't red from someone else's outage.
21
+ - Commit dictionaries and ignore lists; reviewers should see what's being suppressed.
22
+ - Treat new violations as build failures; warnings get ignored forever.
23
+ - Scope linters to `docs/**` and Markdown — don't let them choke on generated files or vendored content.
24
+ - Vale style rules are opinions: tune them to the team's voice, don't adopt a vendor preset wholesale.
package/skills/docker-compose/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: docker-compose
3
+ description: Write a docker-compose stack that brings up the app plus its dependencies for local dev
4
+ category: ci-cd
5
+ ---
6
+
7
+ # Docker Compose
8
+
9
+ Reach for this when local development needs the app wired to backing services (db, cache, queue) with one command.
10
+
11
+ 1. Inventory the services the app talks to (Postgres, Redis, etc.) from config and connection strings.
12
+ 2. Define one service per process in `docker-compose.yml`; build the app from its Dockerfile, pull pinned images for dependencies.
13
+ 3. Wire connectivity by service name (use `db` as the host, not `localhost`) and pass config via `environment` / `env_file`.
14
+ 4. Add named volumes for data that must persist and bind-mount source for live reload in dev.
15
+ 5. Add `healthcheck` blocks and `depends_on: condition: service_healthy` so the app starts only after deps are ready.
16
+ 6. Run `docker compose up`, verify every service is healthy and the app reaches its dependencies, then document the up/down commands.
17
+
18
+ ## Rules
19
+ - Reference services by their compose name on the internal network, never `localhost`.
20
+ - Pin dependency image tags; keep the app on a build context so code changes rebuild.
21
+ - Use `env_file` for local secrets and keep that file out of git.
22
+ - `depends_on` alone only waits for start — gate on healthchecks for real readiness.
23
+ - Persist stateful data in named volumes so `down` doesn't wipe the dev database unintentionally.
package/skills/dockerize/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dockerize
3
+ description: Write a Dockerfile and .dockerignore that build a small, reproducible image for the app
4
+ category: ci-cd
5
+ ---
6
+
7
+ # Dockerize
8
+
9
+ Use when the app needs a container image to build, ship, or run consistently across environments.
10
+
11
+ 1. Identify the runtime, entrypoint, and exposed port from the project (start script, `main`, server bind address).
12
+ 2. Choose a slim, pinned base image (e.g. `node:20-slim`, `python:3.12-slim`) — avoid `latest`.
13
+ 3. Use a multi-stage build: a builder stage that installs deps and compiles, a final stage that copies only the runtime artifacts.
14
+ 4. Copy dependency manifests first and install before copying source, so layer caching survives source-only edits.
15
+ 5. Run as a non-root user, set `WORKDIR`, `EXPOSE` the port, and use exec-form `CMD`/`ENTRYPOINT` (`["node","server.js"]`).
16
+ 6. Write a `.dockerignore` (`.git`, `node_modules`, build output, `.env`, tests) then `docker build` and run the container to confirm it starts.
17
+
18
+ ## Rules
19
+ - Pin the base image tag/digest; never depend on `latest`.
20
+ - Order layers cheapest-to-change first (deps before source) to maximize cache hits.
21
+ - Never bake secrets or `.env` files into the image — pass them at runtime.
22
+ - Drop to a non-root user before the final `CMD`.
23
+ - A missing `.dockerignore` bloats context and can leak local files — always create one.
package/skills/docstrings/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: docstrings
3
+ description: Add docstrings or JSDoc to public APIs describing behavior, params, returns, and errors
4
+ category: docs
5
+ ---
6
+
7
+ # Docstrings
8
+
9
+ Use this to document the public surface of a module or package so callers understand it without reading the implementation. Focus on exported/public symbols, not every internal helper.
10
+
11
+ 1. Identify the public API: exported functions, classes, methods, and constants that callers depend on.
12
+ 2. Pick the idiomatic format for the language (JSDoc/TSDoc, Python PEP 257 + type-style, Rustdoc `///`, GoDoc comment).
13
+ 3. For each symbol, write a one-line summary, then document params, return value, thrown/raised errors, and side effects.
14
+ 4. Describe behavior and contracts (units, ranges, nullability, ownership) — not a restatement of the signature.
15
+ 5. Add a short usage example for anything non-obvious or easy to misuse.
16
+ 6. Run the doc/lint tooling (`tsc`, `pydocstyle`, `cargo doc`, `go doc`) to confirm the comments parse.
17
+
18
+ ## Rules
19
+ - Document why and how-to-use, never "this function does X" when X is just the name.
20
+ - Don't restate types the signature already conveys; add the constraints it can't.
21
+ - Keep summaries to one imperative line; details go below.
22
+ - Cover error/exception cases and edge behavior — that's what callers can't infer.
23
+ - Skip private/internal helpers unless their behavior is genuinely surprising.
package/skills/dotfiles/SKILL.md ADDED
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: dotfiles
3
+ description: Manage dotfiles and machine setup as a version-controlled, reproducible, idempotent install
4
+ category: shell
5
+ ---
6
+
7
+ # Dotfiles
8
+
9
+ Reach for this when organizing shell/editor/tool config into a repo that bootstraps a new machine the same way every time.
10
+
11
+ 1. Put all configs in one git repo and link them into place with symlinks (or GNU `stow`) so edits in the repo are live immediately.
12
+ 2. Write an idempotent `install.sh` that creates symlinks, backs up any pre-existing real file to `*.bak`, and can be re-run safely without clobbering.
13
+ 3. Separate machine-specific or secret values (tokens, work-vs-personal email) into a gitignored `*.local` file that the tracked config sources at the end.
14
+ 4. Pin tool installs explicitly — a `Brewfile`, `apt` list, or `mise`/`asdf` `.tool-versions` — so package state is reproducible, not implicit.
15
+ 5. Make config files host-aware via conditionals (`$(hostname)`, OS check) rather than maintaining divergent copies per machine.
16
+ 6. Test the bootstrap on a clean container or VM, then document the one-liner to clone and run `install.sh` in the README.
17
+
18
+ ## Rules
19
+ - Never commit secrets, SSH private keys, or API tokens; gitignore `*.local`, `.env`, and key files, and scan history before pushing.
20
+ - Keep `install.sh` idempotent — running it twice must be a no-op, not a pile of duplicate symlinks or appended lines.
21
+ - Back up existing files before symlinking so a first run on a populated home dir doesn't destroy data.
22
+ - Prefer symlinks over copies so the repo stays the single source of truth.
23
+ - Guard OS-specific blocks (`case "$(uname -s)"`) so the same repo works on macOS and Linux.