jay-agent-kit

Étoiles11

Forks4

Mis à jour1 juillet 2026 à 06:11

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.

Installation

Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.

Source

jay-framework

jay-framework/jay

Ouvrir le dépôt GitHub Voir les dépôts du créateur

Téléchargement

Métiers associésSOC

Basé sur la classification professionnelle SOC

Développeurs de logicielsProfessions informatiques et mathématiques·SOC 15-1252

SKILL.md

readonly

Plus depuis ce dépôt

même dépôt

jay-dom-refs

jay-framework/jay

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.

2026-07-0111

jay-html-authoring

jay-framework/jay

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.

2026-07-0111

jay-cli-commands

jay-framework/jay

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.

2026-02-2711

jay-contracts-and-plugins

jay-framework/jay

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.

2026-02-2711

jay-dev-server-test

jay-framework/jay

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.

2026-02-1911

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.

Jay Agent Kit

This is the main entry point for building jay-stack applications. Read the relevant sub-skills as needed.

Overview

Jay Stack is a full-stack framework where:

Plugins provide headless components (data + interactions, no UI)
Contracts define the data shape and interaction points of each component
jay-html templates provide the UI that binds to contract data
Rendering phases determine when data is available (build-time, request-time, client-side)

Workflow

Discover what plugins and contracts are available
Read contracts to understand data shapes and phases
Read references — check agent-kit/references/<plugin>/ for pre-generated discovery data (product catalogs, collection schemas). Faster than CLI commands.
Create jay-html pages that bind to contract data
Validate your files
Test with the dev server

Sub-Skills

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 |

Quick Reference

Rendering Phases

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.

Page File Structure

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)

Headless Components — Two Patterns

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 Full-Stack Components

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.

Discovery Commands

# 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

Key Directories

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`

DOM access (page.ts and headfull components)

Jay Stack owns rendering. When adding interactivity beyond jay-html bindings:

Put structure in jay-html; put state in ViewState signals returned from .withInteractive.
Use refs for events and imperative DOM (exec$ inside handlers only).
Avoid document.querySelector, imperative createElement UI, and document-level drag listeners.

Read jay-dom-refs before reaching for document.*.