菜单
Main entry point for AI agents building jay-stack applications. Use when creating pages, working with headless components, or generating jay-html from contracts. Covers the full workflow from reading contracts to producing valid jay-html pages.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
DOM access in Jay Stack projects — use refs and jay-html ViewState, not document.querySelector or imperative createElement. Use when writing page.ts interactive logic, overlays, drags, focus, measuring elements, or global listeners.
Create and edit jay-html template files with data binding, headless components, conditional rendering, loops, and styling. Also covers directory-based routing in jay-stack. Use when creating pages, editing templates, or setting up routes.
Use jay-stack CLI commands for setup, discovery and validation. Covers jay-stack setup (plugin config and references), jay-stack params (discover URL param values for SSG), jay-stack action (run plugin actions), and jay-stack validate (check jay-html and contract files). Use when discovering data, validating files, or running plugin actions.
Read plugin.yaml files and materialized contracts from the agent-kit to understand available components, data shapes, and rendering phases. Use when you need to discover what plugins/contracts exist or understand a contract's tags before creating jay-html.
Run Jay Stack dev server with test mode for automated testing and CI. Use when running smoke tests, integration tests, or needing reliable server startup/shutdown. Handles health checks, graceful shutdown, and auto-timeout.
| name | jay-agent-kit |
| description | Main entry point for AI agents building jay-stack applications. Use when creating pages, working with headless components, or generating jay-html from contracts. Covers the full workflow from reading contracts to producing valid jay-html pages. |
This is the main entry point for building jay-stack applications. Read the relevant sub-skills as needed.
Jay Stack is a full-stack framework where:
agent-kit/references/<plugin>/ for pre-generated discovery data (product catalogs, collection schemas). Faster than CLI commands.Read these as needed:
| Skill | When to Read |
|---|---|
| jay-html-authoring | Creating or editing .jay-html pages, understanding routing, template syntax, headless components |
| jay-contracts-and-plugins | Reading plugin.yaml, materialized contracts, plugins-index |
| jay-cli-commands | Running jay-stack params, validate, or action commands |
| jay-dev-server-test | Starting dev server in test mode, smoke testing |
| jay-dom-refs | DOM access in page.ts — refs and ViewState first; avoid direct document usage |
Also see the agent-kit generated docs (run jay-stack agent-kit):
agent-kit/project-structure.md — Project layout, styling patterns, CSS themes, configuration || Phase | When | Use For |
|---|---|---|
| slow | Build time (SSG) | Static content, SEO data, pre-rendered lists |
| fast | Request time (SSR) | Per-request data (prices, stock, personalization) |
| fast+interactive | Request + client | Data that also updates on the client |
There is no standalone "interactive" phase. Any tag with type: interactive is automatically fast+interactive. Tags without an explicit phase are available in all phases.
Each page lives in a directory under src/pages/:
src/pages/
├── page.jay-html → /
├── products/
│ ├── page.jay-html → /products
│ └── [slug]/
│ └── page.jay-html → /products/:slug
Each page directory can contain:
page.jay-html — template (required for rendering)page.jay-contract — page-level data contract (optional)page.conf.yaml — configuration: which headless components to use (optional, used when jay-html is missing)1. Key-based (data merged into parent ViewState under a key):
<script
type="application/jay-headless"
plugin="my-plugin"
contract="my-contract"
key="data"
></script>
<!-- Access: {data.fieldName}, ref="data.refName" -->
2. Instance-based (multiple instances with props, inline template):
<script type="application/jay-headless" plugin="my-plugin" contract="my-widget"></script>
<jay:my-widget productId="123">
<h3>{name}</h3>
<button ref="addToCart">Add</button>
</jay:my-widget>
Headfull components own their UI template and participate in three-phase rendering. Add contract to a headfull import:
<script
type="application/jay-headfull"
src="./header/header"
contract="./header/header.jay-contract"
names="header"
></script>
<jay:header logoUrl="/logo.png" />
Headfull FS components can nest other headfull FS or headless components in their own <head>:
<!-- header/header.jay-html — uses a plugin headless inside its template -->
<head>
<script type="application/jay-headless" plugin="my-plugin" contract="cart-indicator"></script>
</head>
<body>
<header>
<jay:cart-indicator><span>{itemCount}</span></jay:cart-indicator>
</header>
</body>
All nested imports are hoisted to the page level. Nesting depth is unlimited. Key-based headless imports are not allowed inside headfull FS components.
# Run plugin setup (config templates, credential validation, reference data)
yarn jay-stack setup
# Materialize contracts and generate indexes
yarn jay-stack agent-kit
# Discover URL params for a contract (SSG routes)
yarn jay-stack params <plugin>/<contract>
# Run a plugin action (e.g., search products)
yarn jay-stack action <plugin>/<action> --input '{"query":"shoes"}'
# Validate all jay-html and contract files
yarn jay-stack validate
| Path | Purpose |
|---|---|
src/pages/ | Page routes (directory-based routing) |
agent-kit/materialized-contracts/ | Generated contracts, indexes (run jay-stack agent-kit) |
agent-kit/references/<plugin>/ | Pre-generated discovery data (run jay-stack agent-kit) |
node_modules/<plugin>/ | Plugin packages with plugin.yaml |
Jay Stack owns rendering. When adding interactivity beyond jay-html bindings:
.withInteractive.exec$ inside handlers only).document.querySelector, imperative createElement UI, and document-level drag listeners.Read jay-dom-refs before reaching for document.*.