diff --git a/pretext-layout/SKILL.md b/pretext-layout/SKILL.md
new file mode 100644
index 00000000..fe7aeac6
--- /dev/null
+++ b/pretext-layout/SKILL.md
@@ -0,0 +1,78 @@
+---
+name: "pretext-layout"
+description: "Integrate, debug, or prototype @chenglou/pretext for browser-based multiline text measurement and manual line layout. Use when replacing DOM height probes, building text-aware virtualization or custom canvas/SVG flows, wiring width plus line-height measurement into frontend code, or diagnosing accuracy issues involving fonts, white-space, emoji, bidi text, and browser-only runtime constraints."
+version: "1.0.0"
+repository: "https://github.com/tachikomared/pretext-agents-skill"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - "bash"
+        - "node"
+        - "npm"
+        - "python3"
+---
+
+
+# Pretext Layout
+
+## Overview
+
+Use Pretext to measure multiline text in browser environments without paying repeated DOM reflow costs in the hot path. Prefer it when text width changes often and you need stable height or per-line geometry from cached measurements.
+
+**Source & Discovery:**
+- Repository: [https://github.com/tachikomared/pretext-agents-skill](https://github.com/tachikomared/pretext-agents-skill)
+- Verified Skill: [https://clawhub.ai/tachikomared/pretext-agents-skill](https://clawhub.ai/tachikomared/pretext-agents-skill)
+
+
+## Workflow
+
+1. Confirm the runtime first.
+   - Treat Pretext as browser-first.
+   - If the task is pure Node or CLI with no `OffscreenCanvas` and no `document`, do not promise direct runtime support.
+2. Match the API to the job.
+   - Use `prepare()` plus `layout()` for height and line-count measurement.
+   - Use `prepareWithSegments()` plus `layoutWithLines()`, `walkLineRanges()`, or `layoutNextLine()` for custom rendering.
+3. Sync layout inputs with real styles.
+   - Read `font` and `line-height` from the target element or design token source.
+   - Wait for `document.fonts.ready` before trusting measurements when web fonts are involved.
+4. Cache aggressively.
+   - Prepare once per `(text, font, whiteSpace, locale)` input.
+   - Reuse the prepared handle across width changes.
+5. Verify against the real UI when accuracy matters.
+   - Compare a few representative strings against live DOM heights.
+   - Include multilingual, emoji, and narrow-width cases if the feature depends on them.
+
+## Decision Guide
+
+- Reach for `prepare()` plus `layout()` when the user needs block height, resize performance, virtualization, scroll anchoring, or pre-measuring text before render.
+- Reach for `prepareWithSegments()` plus rich line APIs when the user needs custom line drawing, canvas text, SVG text, shrink-wrap width discovery, or variable line widths.
+- Reach for ordinary DOM measurement instead when the task depends on CSS behaviors Pretext does not aim to cover fully.
+
+## Core Rules
+
+- Do not claim server-side support unless the target environment actually provides a compatible canvas context.
+- Keep `font` and `lineHeight` aligned with the real UI; measurement errors usually come from mismatched inputs, not from the layout call itself.
+- Avoid `system-ui` for accuracy-sensitive flows on macOS; prefer named fonts.
+- Treat `prepare()` as the expensive step and `layout()` as the hot path.
+- When working with textarea-like content, pass `{ whiteSpace: 'pre-wrap' }` explicitly.
+
+## Implementation Checklist
+
+- Identify the exact text source, target width source, font source, and line-height source.
+- Decide whether the feature only needs height or also needs per-line data.
+- Cache prepared handles instead of calling `prepare()` on every resize.
+- Add a small verification path that compares Pretext output with live DOM for representative samples.
+- Document any unsupported CSS or runtime assumptions close to the integration point.
+
+## Scripts
+
+- Run `scripts/scaffold_browser_demo.py --out <dir>` when you need a minimal browser starter wired to `@chenglou/pretext`.
+- Use the scaffold as a disposable starting point; adapt `font`, `line-height`, white-space mode, and UI markup to the real project after generation.
+
+## References
+
+- Read `references/browser-integration.md` for the common browser setup pattern and a reusable measurement loop.
+- Read `references/usage-patterns.md` when choosing between the simple and rich APIs.
+- Read `references/caveats.md` before answering questions about accuracy, fonts, white-space, emoji, bidi behavior, or non-browser runtimes.
+- Read `references/project-examples.md` for portable integration patterns you can adapt to any browser-based app or AI CLI workspace.
diff --git a/pretext-layout/references/browser-integration.md b/pretext-layout/references/browser-integration.md
new file mode 100644
index 00000000..0db9636c
--- /dev/null
+++ b/pretext-layout/references/browser-integration.md
@@ -0,0 +1,9 @@
+# Browser Integration Guide
+
+## Standard Pattern
+1. Import Pretext in your browser entry point.
+2. Ensure fonts are loaded before measurement:
+   ```javascript
+   await document.fonts.ready;
+   ```
+3. Use a cached layout handle for your UI components.
diff --git a/pretext-layout/references/caveats.md b/pretext-layout/references/caveats.md
new file mode 100644
index 00000000..b1a3853d
--- /dev/null
+++ b/pretext-layout/references/caveats.md
@@ -0,0 +1,27 @@
+# Caveats
+
+## Runtime Constraint
+
+Pretext is browser-oriented. Its measurement layer expects `OffscreenCanvas` or a DOM canvas context. In a pure Node or CLI process without those APIs, direct runtime use should be treated as unsupported unless the user already provides a compatible environment.
+
+## Accuracy Pitfalls
+
+- `system-ui` can be inaccurate on macOS for `layout()`-grade matching; prefer a named font.
+- Web fonts measured before `document.fonts.ready` can produce false mismatches.
+- Incorrect `line-height` inputs can make a good width measurement look wrong.
+- If the product preserves spaces or hard breaks, use `{ whiteSpace: 'pre-wrap' }`.
+
+## Scope Boundaries
+
+Pretext targets common multiline wrapping behavior, not every CSS text feature. If a task depends on unusual CSS combinations or exact browser text rendering edge cases beyond the library's stated scope, keep that limitation explicit.
+
+## Debug Order
+
+When a user reports a mismatch, check in this order:
+
+1. runtime is actually browser-backed
+2. fonts are loaded
+3. `font` matches the real element
+4. `line-height` matches the real element
+5. `whiteSpace` mode matches the content
+6. the sample string includes edge cases such as emoji or bidi text
diff --git a/pretext-layout/references/project-examples.md b/pretext-layout/references/project-examples.md
new file mode 100644
index 00000000..cdea910c
--- /dev/null
+++ b/pretext-layout/references/project-examples.md
@@ -0,0 +1,34 @@
+# Portable Integration Patterns
+
+Use these shapes when adapting the skill to a public repository or another AI CLI workspace.
+
+## Plain browser measurement
+
+- one page with editable text
+- one width control
+- one live DOM paragraph for verification
+- one pretext measurement path that reports height, line count, and delta
+
+## Chat or transcript UI
+
+- assistant and user bubbles with fixed inner text width
+- predicted bubble height from Pretext before the final DOM read
+- verification stats such as total predicted height, total DOM height, and largest delta
+
+## React integration
+
+- one shared measurer outside the component render path
+- `useEffect` or equivalent font-ready boot step
+- `useLayoutEffect` or equivalent post-render verification step
+- width-driven recomputation that reuses cached prepared handles
+
+## Reusable helper responsibilities
+
+- read the real `font` value
+- read the real `line-height` value
+- wait for `document.fonts.ready` when available
+- cache prepared handles by `(text, font, whiteSpace, locale)`
+
+## Host compatibility note
+
+This skill is written to stay usable across AI CLIs and compatible skill systems. Keep host-specific wrappers, install docs, or UI metadata outside the exported runtime bundle unless a target platform explicitly requires them.
diff --git a/pretext-layout/references/usage-patterns.md b/pretext-layout/references/usage-patterns.md
new file mode 100644
index 00000000..249af70b
--- /dev/null
+++ b/pretext-layout/references/usage-patterns.md
@@ -0,0 +1,48 @@
+# Usage Patterns
+
+## `prepare()` + `layout()`
+
+Choose this pair for:
+
+- chat bubbles
+- message lists
+- feed cards
+- virtualization
+- resize-driven height recalculation
+- scroll anchoring
+
+Mental model:
+
+- `prepare()` does analysis and measurement once.
+- `layout()` is the cheap repeat call for each width.
+
+## `prepareWithSegments()` + `layoutWithLines()`
+
+Choose this when the caller needs actual line text and widths for fixed-width layouts.
+
+Typical uses:
+
+- drawing text into canvas
+- SVG text placement
+- editorial or poster-like layouts
+- custom line highlighting
+
+## `walkLineRanges()`
+
+Choose this when the caller needs geometry without building line strings.
+
+Typical uses:
+
+- shrink-wrap width search
+- balanced-width experiments
+- width-vs-height optimization loops
+
+## `layoutNextLine()`
+
+Choose this when line widths vary while the paragraph flows.
+
+Typical uses:
+
+- text wrapping around floated media
+- magazine-like irregular columns
+- staged layout where each row has a different available width