AgentSkillsCN

observable-framework

构建并维护Observable Framework站点。当任务涉及`@observablehq/framework`时，可选用此方案，包括创建或编辑`src/*.md`页面、实现`src/data/*`加载器、添加可复用的`src/components/*`模块、更新`observablehq.config.js`，或调试预览/构建/部署相关的问题。

SKILL.md
--- frontmatter
name: observable-framework
description: Build and maintain Observable Framework sites. Use when tasks involve `@observablehq/framework`, including creating or editing `src/*.md` pages, implementing `src/data/*` loaders, adding reusable `src/components/*` modules, updating `observablehq.config.js`, or debugging preview/build/deploy issues.

Observable Framework

Follow this workflow:

  1. •Inspect package.json scripts and observablehq.config.js (root, pages, theme, head) before editing.
  2. •Keep content under the configured root (src/ in this project).
  3. •Implement the smallest change that satisfies the request, then run a relevant check (npm run build or targeted command).

Work on Pages

  • •Create pages as Markdown files in src/ (for example src/wheel-analysis.md).
  • •Use JavaScript code fences for reactive logic and charts.
  • •Use FileAttachment("data/<file>") for data snapshots generated by loaders.
  • •If navigation needs manual ordering, update pages in observablehq.config.js.

Work on Data Loaders

  • •Put loaders in src/data/.
  • •Use *.js loaders that fetch/transform data and write to stdout (build captures output as data files).
  • •Fail fast on non-OK HTTP responses and keep transformations deterministic.
  • •Normalize high-cardinality fields when charts require readable legends.

Work on Components

  • •Put reusable modules in src/components/.
  • •Export plain functions that return Observable-compatible renderables (for example Plot charts).
  • •Keep width/height configurable through function options.

Commands

  • •Dev server: npm run dev
  • •Production build: npm run build
  • •Deploy: npm run deploy
  • •CLI passthrough: npm run observable -- <args>

For common patterns and troubleshooting, read references/common-workflows.md.