refactor(skills): share the project token and host bullets

context/shared/project-token-and-host.md

@@ -0,0 +1,7 @@
+---
+title: Get the PostHog project token and host
+---
+
+- If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
+- If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
+- For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.

context/skills/omnibus/instrument-error-tracking/description.md

@@ -43,9 +43,7 @@ STEP 6: Upload source maps (frontend/mobile only).
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
   - List the key names in `.env.example`, or the env template the project already uses, with placeholder values, so the next developer knows what to set. Create `.env.example` if the project has none. Never put real values in it.

context/skills/omnibus/instrument-feature-flags/description.md

@@ -37,9 +37,7 @@ STEP 5: Instrument the feature.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
   - List the key names in `.env.example`, or the env template the project already uses, with placeholder values, so the next developer knows what to set. Create `.env.example` if the project has none. Never put real values in it.

context/skills/omnibus/instrument-integration/description.md

@@ -37,9 +37,7 @@ STEP 5: Identify users.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - Write these values to the appropriate env file (e.g. `.env.local` for Next.js, `.env` for others) using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
   - List the key names in `.env.example`, or the env template the project already uses, with placeholder values, so the next developer knows what to set. Create `.env.example` if the project has none. Never put real values in it.

context/skills/omnibus/instrument-llm-analytics/description.md

@@ -39,9 +39,7 @@ STEP 5: Link to users.
 
 STEP 6: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
   - List the key names in `.env.example`, or the env template the project already uses, with placeholder values, so the next developer knows what to set. Create `.env.example` if the project has none. Never put real values in it.

context/skills/omnibus/instrument-logs/description.md

@@ -40,9 +40,7 @@ STEP 6: Add structured properties.
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - For the OpenTelemetry endpoint, use the same host as above with the path `/v1`: `https://us.i.posthog.com/v1` (US) or `https://eu.i.posthog.com/v1` (EU).
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.

context/skills/omnibus/instrument-metrics/description.md

@@ -35,9 +35,7 @@ STEP 5: Keep cardinality low.
 
 STEP 6: Set up environment variables. (Skip if the PostHog SDK is already configured — `posthog.metrics` reuses the SDK's existing project token.)
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - For the OTLP metrics endpoint, use the same host as above with the path `/i/v1/metrics`: `https://us.i.posthog.com/i/v1/metrics` (US) or `https://eu.i.posthog.com/i/v1/metrics` (EU), with the project token as an `Authorization: Bearer` header.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.

context/skills/omnibus/instrument-product-analytics/description.md

@@ -52,9 +52,7 @@ STEP 8: Add error tracking.
 
 STEP 9: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
+  {{> project-token-and-host}}
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.
   - List the key names in `.env.example`, or the env template the project already uses, with placeholder values, so the next developer knows what to set. Create `.env.example` if the project has none. Never put real values in it.

context/skills/omnibus/instrument-tracing/description.md

@@ -60,10 +60,8 @@ STEP 6: Link spans to people and sessions. (Optional.)
 
 STEP 7: Set up environment variables.
   - Check if the project already has PostHog environment variables configured (e.g. in `.env`, `.env.local`, or framework-specific env files). If valid values already exist, skip this step.
-  - If the PostHog project token is missing, use the project token that the tool or CLI which started this setup already gave you (for example in its output or instructions).
-  - If it gave you none, call the PostHog MCP server's `projects-get` tool to list the projects. If more than one comes back, ask the user which project to use. Then call `project-get` with that project's `id` and read its `api_token`. Before you write the token, tell the user the project's `name` and confirm it is the one this app should send to. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
+  {{> project-token-and-host}}
   - Use the project token (it starts with `phc_`). Do not use a personal API key (it starts with `phx_`).
-  - For the PostHog host URL: use the host that the tool or CLI which started this setup already gave you. If it gave you none, use the `api_host` field of the `project-get` response. If you still have no host from the calling tool, the MCP response, or existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
   - For the OTLP traces endpoint, use the same host as above with the path `/i/v1/traces`: `https://us.i.posthog.com/i/v1/traces` (US) or `https://eu.i.posthog.com/i/v1/traces` (EU), with the project token as an `Authorization: Bearer` header.
   - Write these values to the appropriate env file using the framework's naming convention.
   - Reference these environment variables in code instead of hardcoding them.

scripts/dev-server.js

@@ -3,10 +3,11 @@
 /**
  * Development server for MCP resources
  *
- * Runs one full build at startup, then watches context/skills/
+ * Runs one full build at startup, then watches context/skills/, context/shared/
  * and example-apps/ for changes. A file edit triggers an incremental rebuild of
- * only the skills that own the path; manifest.json and skill-menu.json are
- * regenerated from the in-memory skill list. The bundled
+ * only the skills that own the path, or of every skill for an edit under
+ * context/shared/, since any skill may include a partial. manifest.json and
+ * skill-menu.json are regenerated from the in-memory skill list. The bundled
  * skills-mcp-resources.zip and marketplace tree stay at initial-build state
  * until the next manual `npm run build`.
  *
@@ -51,6 +52,7 @@ const configDir = path.join(repoRoot, 'context');
 const distDir = path.join(repoRoot, 'dist');
 const skillsDir = path.join(distDir, 'skills');
 const skillsSourceDir = path.join(configDir, 'skills');
+const sharedSourceDir = path.join(configDir, 'shared');
 const agentsSourceDir = path.join(configDir, 'agents');
 const agentsDir = path.join(distDir, 'agents');
 const exampleAppsDir = path.join(repoRoot, 'example-apps');
@@ -213,7 +215,7 @@ function handleEvent(event, absPath) {
         event,
         absPath,
         indexes,
-        paths: { repoRoot, skillsDir: skillsSourceDir, exampleAppsDir },
+        paths: { repoRoot, skillsDir: skillsSourceDir, sharedDir: sharedSourceDir, exampleAppsDir },
     });
 
     const relPath = path.relative(repoRoot, absPath);
@@ -234,7 +236,7 @@ function handleEvent(event, absPath) {
 
 function setupWatcher() {
     const sep = path.sep;
-    const watcher = chokidar.watch([skillsSourceDir, agentsSourceDir, exampleAppsDir], {
+    const watcher = chokidar.watch([skillsSourceDir, sharedSourceDir, agentsSourceDir, exampleAppsDir], {
         ignoreInitial: true,
         persistent: true,
         followSymlinks: false,
@@ -246,6 +248,7 @@ function setupWatcher() {
 
     console.log('\n👀 Watching:');
     console.log(`   📁 ${path.relative(repoRoot, skillsSourceDir)}`);
+    console.log(`   📁 ${path.relative(repoRoot, sharedSourceDir)}`);
     console.log(`   📁 ${path.relative(repoRoot, agentsSourceDir)}`);
     console.log(`   📁 ${path.relative(repoRoot, exampleAppsDir)}`);
 

scripts/lib/change-router.js

@@ -81,6 +81,10 @@ function findExamplesMatching(relPathPosix, examplePathIndex) {
     return [...ids];
 }
 
+function everySkillId(groupRoots) {
+    return groupRoots.flatMap(group => group.variantIds);
+}
+
 /**
  * Route a chokidar event to skill IDs.
  *
@@ -93,7 +97,11 @@ function findExamplesMatching(relPathPosix, examplePathIndex) {
  */
 function routeChange({ event, absPath, indexes, paths }) {
     const { groupRoots, examplePathIndex } = indexes;
-    const { repoRoot, skillsDir, exampleAppsDir } = paths;
+    const { repoRoot, skillsDir, sharedDir, exampleAppsDir } = paths;
+
+    if (isUnder(absPath, sharedDir)) {
+        return { ids: everySkillId(groupRoots) };
+    }
 
     if (isUnder(absPath, skillsDir)) {
         const isDirEvent = event === 'addDir' || event === 'unlinkDir';

scripts/lib/skill-generator.js

@@ -55,16 +55,20 @@ function loadYaml(configPath) {
 // A line that is exactly `{{> name}}` is replaced at build time with the body
 // of `<configDir>/shared/name.md` (frontmatter stripped), so shared prose like
 // the MCP tool-calling grammar lives in one canonical file and every skill that
-// includes it stays in sync.
-const PARTIAL_DIRECTIVE = /^[ \t]*\{\{>\s*([a-z0-9-]+)\s*\}\}[ \t]*$/gm;
+// includes it stays in sync. Each included line takes the directive's leading
+// whitespace, so an indented directive nests the partial under its list item.
+const PARTIAL_DIRECTIVE = /^([ \t]*)\{\{>\s*([a-z0-9-]+)\s*\}\}[ \t]*$/gm;
 
 function expandPartials(body, configDir) {
-    return body.replace(PARTIAL_DIRECTIVE, (_match, name) => {
+    return body.replace(PARTIAL_DIRECTIVE, (_match, indent, name) => {
         const partialPath = path.join(configDir, 'shared', `${name}.md`);
         if (!fs.existsSync(partialPath)) {
             throw new Error(`Partial include {{> ${name}}} references missing file ${partialPath}`);
         }
-        return matter(fs.readFileSync(partialPath, 'utf8')).content.trim();
+        return matter(fs.readFileSync(partialPath, 'utf8')).content.trim()
+            .split('\n')
+            .map(line => (line ? indent + line : line))
+            .join('\n');
     });
 }