Feat/add engage rt personalization playbook

[TD-Ko-SHI]

Summary

Add end-to-end playbook for delivering dynamic in-app content via Engage Studio + RT Personalization API.

What's New

• Playbook: playbooks/engage-rt-personalization

  • Complete 6-step workflow (RT config → personalization service → Engage content → frontend integration)
  • Core concepts: Entry criteria, payload types, three-layer architecture
  • Common patterns: product-specific messages, user segments, A/B testing
  • Best practices: start simple, test with curl before frontend
  • Troubleshooting: empty offers, CORS errors, API latency

• Plugin registration: Added playbooks plugin to marketplace.json

[Copilot]

Pull request overview

Adds a new end-to-end “Engage Studio + RT Personalization” playbook to the repository and registers playbooks in the marketplace so the assistant can route relevant prompts to this new workflow.

Changes:

• Introduces the playbooks/engage-rt-personalization playbook with a 6-step implementation + verification guide.
• Adds a playbooks index (playbooks/README.md) and registers the playbook via a new playbooks marketplace plugin.
• Extends trigger tests to route common “personalized in-app popup” prompts to engage-rt-personalization.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/trigger-tests.yml	Adds trigger test prompts mapping to the new playbook skill name.
playbooks/engage-rt-personalization/steps/00-prerequisite.md	Adds internal prerequisite step for RT/Reactor provisioning.
playbooks/engage-rt-personalization/steps/01-configure-realtime.md	Documents RT 2.0 setup (event tables, key events, attributes, stitching).
playbooks/engage-rt-personalization/steps/02-configure-personalization.md	Documents personalization service creation + token setup.
playbooks/engage-rt-personalization/steps/03-audience-studio-setup.md	Documents creating Personalization + Sections and configuring entry criteria/payloads.
playbooks/engage-rt-personalization/steps/04-engage-studio-content.md	Documents designing and linking Engage Studio in-app content.
playbooks/engage-rt-personalization/steps/05-frontend-integration.md	Provides frontend SDK integration + rendering examples.
playbooks/engage-rt-personalization/steps/06-verification.md	Adds end-to-end verification, debugging, and monitoring guidance.
playbooks/engage-rt-personalization/SKILL.md	Adds the playbook skill overview, patterns, and references.
playbooks/README.md	Adds a playbooks index page linking to the new playbook.
.claude-plugin/marketplace.json	Registers a new playbooks plugin pointing at the playbook skill.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The initialization example sets host: 'in.treasuredata.com', but elsewhere in the repo the JS SDK guidance uses regional streaming hosts like us01.records.in.treasuredata.com (see sdk-skills/javascript/SKILL.md). Using the non-regional host here can lead to events being sent to the wrong endpoint or failing in newer SDK versions.

[Copilot]

The playbook links to ../examples/, but this PR doesn't add an examples/ directory under playbooks/engage-rt-personalization/, so this will be a dead link. Add the examples directory/files or remove the reference.

Suggested change

- **Code examples:** [examples/](../examples/)

[Copilot]

The listed example files under examples/ (examples/frontend-integration.html, examples/personalization-payload.json) are not included in this PR and there is no examples/ directory under playbooks/engage-rt-personalization/, so these links will be broken. Add the referenced files or update/remove the links.

Suggested change

	- [Complete frontend integration](examples/frontend-integration.html) — Full working example with HTML/JavaScript
	- [Personalization payload samples](examples/personalization-payload.json) — API response examples
	- Complete frontend integration — See the HTML/JavaScript examples included in this playbook for fetching and rendering personalized content.
	- Personalization payload samples — See the request/response payload examples in this playbook for API usage patterns.

[Copilot]

This second example snippet also uses host: 'in.treasuredata.com'. If you update the earlier initialization guidance to use the regional *.records.in.treasuredata.com host (per sdk-skills/javascript/SKILL.md), please update this snippet too so readers don’t copy a non-working config.

Suggested change

	host: 'in.treasuredata.com',
	host: 'YOUR_REGION.records.in.treasuredata.com',

[Copilot]

The troubleshooting section hard-codes https://cdn.treasuredata.com/sdk/4.4/td.min.js, which conflicts with the repo’s documented JS SDK version (v4.4.1 in sdk-skills/javascript/SKILL.md). Keeping the version consistent in both the loader snippet and troubleshooting avoids sending users to a potentially different build.

Suggested change

	- Verify CDN URL is correct: `https://cdn.treasuredata.com/sdk/4.4/td.min.js`
	- Verify CDN URL is correct: `https://cdn.treasuredata.com/sdk/4.4.1/td.min.js`

[Copilot]

This link points to ../examples/frontend-integration.html, but there is no examples/ directory under playbooks/engage-rt-personalization/ in this PR, so the reference will be broken. Either add the referenced example file(s) or remove/adjust the link to an existing location.

Suggested change

	See [examples/frontend-integration.html](../examples/frontend-integration.html) for a complete working example.
	A complete working example is provided below in this section.

[Copilot]

The Network tab guidance references event tracking requests posting to in.treasuredata.com, but the JS SDK guidance in this repo uses regional ingestion hosts (e.g., us01.records.in.treasuredata.com). Consider updating this to match the actual endpoints users should see in DevTools to avoid confusion during verification.

Suggested change

	- Check event tracking requests (POST to in.treasuredata.com)
	- Check event tracking requests (POST to your regional ingestion host, e.g. `us01.records.in.treasuredata.com`)

[Copilot]

The browser-console fetch() example includes Authorization: 'TD1 YOUR_MASTER_API_KEY'. A master API key must never be used client-side (it’s fully privileged and will be exposed to anyone with DevTools). For client-side testing, use only the public personalization service token if supported by the endpoint, or route the request through a server-side proxy that injects credentials.

Suggested change

	// Test from console on your domain
	fetch('https://<p13n_host>/<database>/<event_table>', {
	method: 'POST',
	headers: {
	'Content-Type': 'application/vnd.treasuredata.v1+json',
	'Authorization': 'TD1 YOUR_MASTER_API_KEY',
	// Test from console on your domain using only a browser-safe personalization token.
	// Never put a master API key in client-side code or the browser console.
	// If this endpoint requires privileged authentication, call it through your server instead.
	fetch('https://<p13n_host>/<database>/<event_table>', {
	method: 'POST',
	headers: {
	'Content-Type': 'application/vnd.treasuredata.v1+json',

[Copilot]

The fenced code block starting with markdown contains a nested javascript block, which will prematurely close the outer fence in most Markdown renderers and break formatting. Use indented code blocks inside the example document, or switch the outer fence to a longer delimiter (e.g., ````markdown) so inner triple-backticks render correctly.

Suggested change

```

[Copilot]

The SDK loader uses https://cdn.treasuredata.com/sdk/4.4/td.min.js, but the repo’s td-javascript-sdk skill documents v4.4.1. Using an explicit patch version here (matching the documented one) helps avoid unexpected behavior changes and keeps guidance consistent.

Suggested change

	n.src="https://cdn.treasuredata.com/sdk/4.4/td.min.js";
	n.src="https://cdn.treasuredata.com/sdk/4.4.1/td.min.js";

[doryokujin]

Concerns before reviewing individual changes

I'd like to raise two higher-level concerns that should be resolved before this PR can move forward, before going through the inline feedback.

1. Internal operations in a public repository

td-skills is a public repository that customers install via /plugin marketplace add https://github.com/treasure-data/td-skills. With this PR, the following internal-only content would ship to customer environments:

• steps/00-prerequisite.md documents the internal admin panel, Reactor provisioning workflow, and commands like tdx-admin reactor status that do not exist for customers.
• The *(TD internal only)* annotation does not prevent this — the content is still loaded into customer Claude sessions when the skill is installed.

Concrete user-facing risks:

• A customer's Claude may suggest running tdx-admin commands that don't work in their environment, causing confusion and support tickets.
• The existence, naming, and granularity of internal tooling becomes visible outside TD.

2. The audience is too narrow for td-skills, and internal-only content belongs elsewhere

Customers who can actually run this playbook need all of: RT 2.0 enabled (limited contract) + Engage Studio + in-app messaging + in-house frontend JS SDK integration. That's a very small subset of td-skills users.

Suggested path forward:

• If the content is internal / SE / CS enablement → it belongs in td-internal-skills (or equivalent TD-employee-only repo), not here.
• When it's time to hand this to a specific customer → use the upcoming skill-share feature to deliver it directly, rather than publishing it through the public marketplace.

---

If the decision is still to land this in td-skills

Then please address the following before merging:

Security / correctness (must-fix)

• [Security] SKILL.md:332 — the browser-console fetch() example hard-codes Authorization: 'TD1 YOUR_MASTER_API_KEY'. A master API key must never be placed in client-side code. Apply Copilot's suggested fix (use only a personalization token, or proxy through a server).
• All 10 Copilot review comments are currently unaddressed across 5 commits. Please walk through each — they are all legitimate.

Broken references

• examples/ is referenced from SKILL.md:359, steps/05-frontend-integration.md:304, steps/06-verification.md:507, and playbooks/README.md, but no examples/ directory is included in this PR. Either add the files or remove the references.

Consistency with existing skills

• SDK host: this playbook uses in.treasuredata.com, while sdk-skills/javascript/SKILL.md uses regional hosts (e.g. us01.records.in.treasuredata.com). Please align.
• SDK version: this playbook uses /sdk/4.4/td.min.js; sdk-skills/javascript documents 4.4.1. Use the explicit patch version.
• Steps 1–3 overlap heavily with realtime-skills:rt-setup-personalization, Step 4 with tdx-skills:engage, and Step 5 with sdk-skills:javascript. Consider delegating to those skills instead of re-documenting, and keep this playbook focused on the Engage ↔ RT ↔ Frontend integration glue (its real differentiator).

Structure / placement

• A new top-level playbooks/ category for a single playbook (N=1) is premature. It also cannot naturally sit under studio-skills/ (auto-enabled for all customers, but this feature is RT-gated) — which reinforces the audience concern above.
• playbooks/README.md follows a pattern only used by realtime-skills/ and aps-doc-skills/. Category-level READMEs are not standard in this repo; skill triggering should be driven by the SKILL.md `description` field, not READMEs.