Add installable SmarkForm AI skill specs and wire them into agent docs

AGENTS.md

@@ -40,6 +40,7 @@ When you change or add any of the following, please update this file to reflect
 - scripts/* (collector, build scripts, live-serve helpers)
 - rollup.config.js or rollup-plugins/
 - docs/ content, co-located examples, or test collection logic
+- skills/* (installable AI skill specifications)
 - .github/workflows/* (CI / Pages deployment)
 
 For convenience, include this exact sentence in the PR description when you want the assistant to update AGENTS.md automatically:
@@ -360,6 +361,20 @@ When you discover a new pattern, fix a bug caused by an undocumented constraint,
 3. **Correct inaccurate entries** whenever you verify that something documented is wrong.
 4. You do not need a special PR description sentence to update `AGENTS/` files — just do it as part of your normal work.
 
+## Agent Skills Directory (`skills/`)
+
+The `skills/` directory contains installable skill specifications that can be
+copied into AI tools (opencode and similar) to enforce SmarkForm-specific
+implementation behavior.
+
+| File | Purpose |
+|------|---------|
+| `skills/SmarkForm-Form-Builder.skill.md` | Core skill for implementing SmarkForm forms with required rules and a mandatory compliance checklist |
+| `skills/SmarkForm-Advanced-Internals.skill.md` | Optional advanced skill for internals-heavy work (action semantics, list/context edge cases, security-sensitive patterns) |
+
+Maintenance rule:
+- When `docs/_resources/AGENTS/SmarkForm-Forms.md` or `docs/_resources/AGENTS/SmarkForm-Usage.md` changes, review and update both skill files in `skills/` if affected; when in doubt, update both in the same PR so installable skills stay aligned with canonical docs.
+
 
 - **Contributing**: See `CONTRIBUTING.md`
 - **Documentation**: [https://smarkform.bitifet.net](https://smarkform.bitifet.net)

docs/_resources/ai-agents.md

@@ -17,11 +17,16 @@ nav_order: 6
 
 * [Agent Knowledge Files](#agent-knowledge-files)
 * [How to Use These Files When Prompting an AI](#how-to-use-these-files-when-prompting-an-ai)
-    * [Quick Reference Prompts](#quick-reference-prompts)
+  * [Quick Reference Prompts](#quick-reference-prompts)
+* [Installable Skills](#installable-skills)
+  * [Core Skill (recommended)](#core-skill-recommended)
+  * [Optional Advanced Skill](#optional-advanced-skill)
+  * [Import into opencode or similar tools](#import-into-opencode-or-similar-tools)
+* [Maintenance Rules for Skill Files](#maintenance-rules-for-skill-files)
 * [Prompt Templates](#prompt-templates)
-    * [Simple form](#simple-form)
-    * [Form with a repeating list](#form-with-a-repeating-list)
-    * [Adding SmarkForm to an existing page](#adding-smarkform-to-an-existing-page)
+  * [Simple form](#simple-form)
+  * [Form with a repeating list](#form-with-a-repeating-list)
+  * [Adding SmarkForm to an existing page](#adding-smarkform-to-an-existing-page)
 
 <!-- vim-markdown-toc -->
      " | markdownify }}
@@ -62,6 +67,54 @@ Load SmarkForm from CDN (pin to the latest stable version).
 
 ---
 
+## Installable Skills
+
+The repository includes installable skill specs so AI tools can enforce
+SmarkForm-specific implementation rules.
+
+### Core Skill (recommended)
+
+- `skills/SmarkForm-Form-Builder.skill.md`
+
+Use this for general SmarkForm form implementation. It enforces:
+- source-priority lookups (deployed docs first)
+- event/action-first implementation patterns
+- required `await myForm.rendered` timing
+- list/context/template rules
+- root-level security option rules
+- mandatory “SmarkForm compliance checklist” in outputs
+
+### Optional Advanced Skill
+
+- `skills/SmarkForm-Advanced-Internals.skill.md`
+
+Use this when handling advanced internals and edge cases.
+
+### Import into opencode or similar tools
+
+1. Open the desired skill file from `skills/`.
+2. Copy its full content into your tool's skill/instruction definition.
+3. Keep the source-priority section unchanged so the agent always prefers:
+   - `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Forms`
+   - `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage`
+4. If your tool supports separate skills, install:
+   - core skill as default
+   - advanced skill as opt-in
+
+---
+
+## Maintenance Rules for Skill Files
+
+- When `docs/_resources/AGENTS/SmarkForm-Forms.md` or `docs/_resources/AGENTS/SmarkForm-Usage.md` changes, review and update both `skills/SmarkForm-Form-Builder.skill.md` and `skills/SmarkForm-Advanced-Internals.skill.md` if affected; when in doubt, update both in the same PR.
+- Apply the same update rule when their deployed equivalents change:
+  `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Forms` and
+  `https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage`.
+- Keep the source-priority order intact so deployed docs remain the primary
+  knowledge source for agents.
+- If behavioral rules change, update both the skill file(s) and this page.
+
+---
+
 ## Prompt Templates
 
 The following ready-to-use prompts are reproduced from the

skills/SmarkForm-Advanced-Internals.skill.md

@@ -0,0 +1,38 @@
+# SmarkForm Advanced Internals — Optional Skill Spec
+
+## Goal
+
+Handle advanced SmarkForm internals safely (complex list semantics, action decorator nuances, context/target path edge-cases, and security-related options).
+
+## Scope
+
+Use this optional skill for:
+- Nested list/template edge cases
+- Programmatic action invocation nuances
+- Complex `context` / `target` path behavior
+- Mixin/security-option-sensitive implementations
+
+For standard form implementation, use:
+- `skills/SmarkForm-Form-Builder.skill.md`
+
+## Source Priority
+
+Use the exact source-priority order defined in:
+- `skills/SmarkForm-Form-Builder.skill.md`
+
+Additionally, for internals-first tasks, start by reading:
+- https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage
+
+## Non-negotiable Internals Rules
+
+- Respect `@action` calling conventions (including argument position semantics).
+- Respect action context resolution and target resolution semantics.
+- Respect list template role lifecycle and cloning behavior.
+- Apply security-related options at root-level constructor options.
+
+## Output Requirement
+
+Provide a short “advanced compliance check” confirming:
+- source pages consulted
+- internals rules applied
+- unresolved ambiguity (if any)

skills/SmarkForm-Form-Builder.skill.md

@@ -0,0 +1,86 @@
+# SmarkForm Form Builder — Installable Skill Spec
+
+## Goal
+
+Generate production-ready SmarkForm forms that follow current SmarkForm patterns and avoid common implementation mistakes.
+
+## Source Priority (mandatory)
+
+When implementing or modifying forms, consult sources in this order:
+
+1. **Primary (always first):**
+   - https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Forms
+   - https://smarkform.bitifet.net/resources/AGENTS/SmarkForm-Usage
+2. **Fallback (repo source of canonical pages):**
+   - `docs/_resources/AGENTS/SmarkForm-Forms.md`
+   - `docs/_resources/AGENTS/SmarkForm-Usage.md`
+3. **Last fallback (repo pointers):**
+   - `AGENTS/SmarkForm-Forms.md`
+   - `AGENTS/SmarkForm-Usage.md`
+
+If sources disagree, prefer the highest-priority source.
+
+## Required Rules (hard requirements)
+
+1. **Event/action integration**
+   - Use SmarkForm actions and SmarkForm events (`BeforeAction_*` / `AfterAction_*`) for form workflows.
+   - Do not replace SmarkForm action flows with arbitrary ad-hoc DOM listeners on managed form controls.
+2. **Render timing**
+   - Always wait for `await myForm.rendered` before any `find()` usage or component-tree-dependent logic.
+3. **List/template/context semantics**
+   - Follow list template role rules (`item`, `empty_list`, `header`, `footer`, etc.).
+   - Respect context/target resolution semantics for triggers.
+   - For controls inside cloned item templates that target sub-lists, use safe placement patterns documented in SmarkForm Usage.
+4. **Security/root options**
+   - Security-sensitive options must be configured on the root SmarkForm constructor options (not via nested `data-smark` inheritance tricks).
+   - Keep secure defaults unless explicit requirement justifies opt-in.
+5. **Naming convention in examples**
+   - Use `myForm` as the SmarkForm instance variable in generated JS examples.
+
+## Standard Implementation Workflow
+
+1. Read primary source pages.
+2. Draft HTML with `data-smark` attributes on all managed fields.
+3. Initialize with:
+   - `const myForm = new SmarkForm(document.getElementById("myForm"), options);`
+   - `await myForm.rendered;`
+4. Wire behavior through SmarkForm actions/events.
+5. Validate against the compliance checklist below.
+
+## Output Contract
+
+Every response that delivers SmarkForm code must include:
+
+1. The implementation.
+2. A **SmarkForm compliance checklist** section showing pass/fail for each item.
+
+If any checklist item fails, the skill must treat output as incomplete and revise
+it before finalizing. If revision is not possible, add a clear warning header
+(`SmarkForm compliance incomplete`) and explicitly report unmet items and why.
+
+## SmarkForm Compliance Checklist (mandatory)
+
+Template below is intentionally unchecked in this skill spec. In generated
+outputs, agents must replace it with explicit pass/fail marks per item.
+
+When generating output, evaluate each item and report explicit pass/fail status.
+Replace template markers with:
+- `[x]` for pass
+- `[ ]` for fail
+Do not leave this section as an untouched unchecked template.
+
+- [ ] Managed fields include `data-smark`.
+- [ ] Root element is passed to `new SmarkForm(...)` correctly.
+- [ ] Uses `myForm` variable naming convention.
+- [ ] `await myForm.rendered` before `find()` and component-dependent logic.
+- [ ] Uses SmarkForm actions/events for form workflows (`BeforeAction_*` / `AfterAction_*`) where applicable.
+- [ ] List template roles and placement rules are respected.
+- [ ] `context` / `target` paths follow SmarkForm rules.
+- [ ] No conflicting dual defaults (`value=""` plus JSON `"value"` on same element).
+- [ ] Security-sensitive options are set at root constructor options when needed.
+- [ ] Production CDN examples use explicit version numbers (for example `@0.16.0`) and do not use `@latest`.
+
+## Distribution Notes
+
+- This file is the canonical core skill artifact in-repo.
+- For external tools (opencode, similar), adapt this spec to tool-specific front matter/format without changing behavioral rules.