Menu
Use when a developer adds a new page block to this CMS and needs to wire up semantic search indexing for it. Triggers on: "add block to search", "index new block", "wire up extractor", or any mention of a new block needing search support.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Fallback skill for when the uploadImage MCP tool fails because it cannot read a local file path (e.g., Payload is hosted on Vercel and cannot access the developer's local filesystem). Use ONLY after receiving such an error from uploadImage tool from payload mcp — not proactively. Stages one or more files through Vercel Blob as a temporary transfer layer to work around the local filesystem access limitation.
Use when working in a Next.js project with `cacheComponents: true` in next.config — writing or reviewing React Server Components, adding `'use cache'`, configuring `cacheLife()`/`cacheTag()`, invalidating with `updateTag()`/`revalidateTag()`, debugging Partial Prerendering, or deciding static vs cached vs dynamic boundaries.
Use when adding or publishing a new plugin package in this monorepo, or when CI fails with "cannot publish over previously published versions" after a first manual publish.
Styles applications using Tailwind CSS v4 utilities. Activates when adding styles, restyling components, working with gradients, spacing, layout, flex, grid, responsive design, dark mode, colors, typography, or borders; or when the user mentions CSS, styling, classes, Tailwind, restyle, hero section, cards, buttons, or any visual/UI changes.
Use this skill for anything involving the payload-plugin-ab Payload CMS plugin. Triggers include: installing payload-plugin-ab, configuring its options, asking what it does, troubleshooting errors, upgrading versions, setting up A/B testing, configuring storage adapters, writing Next.js middleware for variant routing, setting up analytics tracking, and answering questions about its API. If the user mentions "payload-plugin-ab", "A/B testing plugin", "variant routing", "ab testing", "abTestingPlugin", or "variant manifest" in any Payload CMS context, always use this skill.
Use when working with Payload projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
| name | payload-block-extractor |
| description | Use when a developer adds a new page block to this CMS and needs to wire up semantic search indexing for it. Triggers on: "add block to search", "index new block", "wire up extractor", or any mention of a new block needing search support. |
Use this skill when a new block has been created at apps/cms/src/blocks/<BlockName>/config.ts
and needs its text extraction wired into semantic search.
Each block owns its extractor at apps/cms/src/blocks/<BlockName>/extractText.ts.
The orchestrator that calls all extractors is apps/cms/src/collections/Page/extractPageText.ts.
The two shared utilities are extractLexicalText and joinText from @/lib/utils/text.
Read apps/cms/src/blocks/<BlockName>/config.ts. Identify all fields and their types.
| Field type | Expression |
|---|---|
text / textarea | block.fieldName |
richText | extractLexicalText(block.fieldName) |
array with sub-fields | (block.items ?? []).flatMap(item => [<recurse sub-fields>]) |
relationship / upload / other | // TODO: manual extraction needed for block.fieldName |
For nested array fields, recurse into sub-fields using the same mapping rules.
apps/cms/src/blocks/<BlockName>/extractText.tsWrite the extractor function in the block's own folder:
import type { <BlockName>Block } from '@/payload-types'
import { extractLexicalText, joinText } from '@/lib/utils/text'
export function extract<BlockName>Text(block: <BlockName>Block): string {
return joinText([
// mapped field expressions
])
}
Example — for a block named Promo with a text field, a richText body, and an items array each having a label text field:
// apps/cms/src/blocks/Promo/extractText.ts
import type { PromoBlock } from "@/payload-types";
import { extractLexicalText, joinText } from "@/lib/utils/text";
export function extractPromoText(block: PromoBlock): string {
return joinText([block.text, extractLexicalText(block.body), ...(block.items ?? []).flatMap((item) => [item.label])]);
}
extractPageText.tsOpen apps/cms/src/collections/Page/extractPageText.ts.
import { extract<BlockName>Text } from '@/blocks/<BlockName>/extractText'
case to the switch inside extractPageBlockText:case 'blockSlug':
return extract<BlockName>Text(block)
The blockSlug is the slug property defined in the block's config.ts.
cd apps/cms && bun run check-types && bun run lint
Fix any errors before committing.
git add apps/cms/src/blocks/<BlockName>/extractText.ts
git add apps/cms/src/collections/Page/extractPageText.ts
git commit -m "feat(search): add text extractor for <BlockName> block"
When a field is a relationship or upload, emit a // TODO rather than guessing:
// TODO: manual extraction needed for block.heroImage (relationship/upload)
Leave the TODO in place and note it in the PR description so a human can decide whether to populate it (e.g. by looking up the related document's title).