rudder-profiles-understand

Name: rudder-profiles-understand
Author: rudderlabs

18stars0forks

How to install rudder-profiles-understand?

rudderlabs/rudder-agent-skills/rudder-profiles-understand

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-profiles-understand

Installs into the current project.

Summary

Explains an existing RudderStack Profiles project by reading YAML, model structure, and output metadata. Use when explaining a Profiles project, summarizing features, reviewing project structure, understanding run output, or for a project health check.

Files · 1

View on GitHub

SKILL.md

1	# RudderStack Profiles Project Understanding
2
3	Read an existing Profiles project and summarize what it builds, how it resolves identities, and what the latest run produced.
4
5	## Workflow
6
7	1. Read project files:
8	- `pb_project.yaml` — entities, id_types, connection, schema_version, and any `feature_views` (`using_ids` re-keys output for activation)
9	- `models/inputs.yaml` — input tables, event streams, ID mappings
10	- `models/profiles.yaml` — entity_vars, id_stitcher config, any `entity_cohort` models (filtered audiences) and `feature_table_model` selections; var_groups scoped with `entity_cohort:` compute over a cohort
11	- `models/sql_models.yaml` (if present) — `sql_template` intermediate models
12	- `models/profiles-ml.yaml` / `models/attribution.yaml` (if present) — propensity / attribution models
13	- `models/optimizations.yaml` / `models/macros.yaml` (if present) — performance flags and reusable macros
14	2. Run `pb show models` to get the model dependency structure.
15	3. Check outputs (if the project has been run; these are profiles-mcp tools the agent calls, not `pb` CLI commands):
16	- Call the profiles-mcp tool `initialize_warehouse_connection(<connection_name>)` once before any `run_query()` — a hard precondition documented in the MCP tool; skipping it produces "warehouse not initialized".
17	- Call `get_profiles_output_details()` for output metadata (output schema, entity/id-graph materials, latest `seq_no`).
18	- Run targeted SQL for health metrics (see references).
19	- Identify the latest `seq_no` and output tables. Materials are named `Material_<model>_<hash>_<seq_no>`; pb also maintains stable views (e.g., `<entity>_var_table`) repointed at the latest material each run — prefer the view.
20	4. Present a summary covering:
21	- What entity the project resolves and which id_types it uses.
22	- Which input tables feed data, how IDs map, and which are event streams vs dimensions.
23	- Which features (entity_vars) are computed, with descriptions.
24	- Whether the project is discrete or incremental: any entity_var with a `merge:` clause (or an id_stitcher / sql_template with `run_type: incremental`) makes the project incremental. Call this out — users who don't know their project is incremental are surprised by checkpoint behavior.
25	- Model dependency structure from `pb show models`.
26	- Latest run details: seq_no, output schema, output tables.
27	- Identity resolution health: stitching ratio, over-stitching candidates.
28	- Read-only graph lenses to offer: `pb audit id_stitcher` (interactive viewer), `pb show idstitcher-report` (pre/post-stitch counts, convergence, largest cluster), and `pb show entity-lookup -v <id_value>` (one entity's stitched IDs and features by any known ID).
29
30	## Incremental vs Discrete
31
32	A project becomes incremental the moment any entity_var declares `merge:`. Consequences worth surfacing:
33
34	- Each run produces a new checkpoint identified by `seq_no`; the previous checkpoint is the baseline, and a run computes the delta (rows since the baseline's `end_time`) and merges it in.
35	- Entity counts across seq_nos show growth, not run-over-run rebuild deltas — the latest seq_no's table is the cumulative view.
36	- For incremental projects, recommend a periodic discrete-vs-incremental side-by-side (a full `--rebase_incremental` run vs the incremental output) to catch silent drift. Migration and merge-correctness details live in `rudder-profiles-update` and `rudder-profiles-debug`.
37
38	## Output Style
39
40	Prefer a short explanatory narrative over a raw dump of YAML or SQL results. The summary should answer:
41
42	- What is this project trying to model?
43	- How do identities stitch together across sources?
44	- What features are being computed and from which inputs?
45	- Is the latest output healthy or are there red flags?
46	- What should the user investigate next?
47
48	## Health Indicators
49
50	When outputs are available, check these metrics via `run_query()`:
51
52	\| Metric \| What it reveals \| Red flag \|
53	\|--------\|----------------\|----------\|
54	\| Stitching ratio (raw IDs vs stitched entities) \| How much identity resolution is happening \| Ratio near 1.0 means stitching is not working \|
55	\| Over-stitching candidates \| Entities with unusually many raw IDs \| Single entity absorbing thousands of IDs \|
56	\| Feature NULL rates \| Data completeness \| NULL rate > 50% on a required feature \|
57	\| Entity count trend across runs \| Growth or regression \| Sudden large drops between seq_nos \|
58
59	## Guardrails
60
61	- This skill is read-only. Do not modify project files.
62	- If the project does not compile or key files are missing, say that clearly before interpreting outputs.
63	-

People who liked this also viewed

6 picks

Type

rudder-profiles-understand

18stars0forks

View on GitHub

How to install rudder-profiles-understand?

rudderlabs/rudder-agent-skills/rudder-profiles-understand

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-profiles-understand

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# RudderStack Profiles Project Understanding
2
3	Read an existing Profiles project and summarize what it builds, how it resolves identities, and what the latest run produced.
4
5	## Workflow
6
7	1. Read project files:
8	- `pb_project.yaml` — entities, id_types, connection, schema_version, and any `feature_views` (`using_ids` re-keys output for activation)
9	- `models/inputs.yaml` — input tables, event streams, ID mappings
10	- `models/profiles.yaml` — entity_vars, id_stitcher config, any `entity_cohort` models (filtered audiences) and `feature_table_model` selections; var_groups scoped with `entity_cohort:` compute over a cohort
11	- `models/sql_models.yaml` (if present) — `sql_template` intermediate models
12	- `models/profiles-ml.yaml` / `models/attribution.yaml` (if present) — propensity / attribution models
13	- `models/optimizations.yaml` / `models/macros.yaml` (if present) — performance flags and reusable macros
14	2. Run `pb show models` to get the model dependency structure.
15	3. Check outputs (if the project has been run; these are profiles-mcp tools the agent calls, not `pb` CLI commands):
16	- Call the profiles-mcp tool `initialize_warehouse_connection(<connection_name>)` once before any `run_query()` — a hard precondition documented in the MCP tool; skipping it produces "warehouse not initialized".
17	- Call `get_profiles_output_details()` for output metadata (output schema, entity/id-graph materials, latest `seq_no`).
18	- Run targeted SQL for health metrics (see references).
19	- Identify the latest `seq_no` and output tables. Materials are named `Material_<model>_<hash>_<seq_no>`; pb also maintains stable views (e.g., `<entity>_var_table`) repointed at the latest material each run — prefer the view.
20	4. Present a summary covering:
21	- What entity the project resolves and which id_types it uses.
22	- Which input tables feed data, how IDs map, and which are event streams vs dimensions.
23	- Which features (entity_vars) are computed, with descriptions.
24	- Whether the project is discrete or incremental: any entity_var with a `merge:` clause (or an id_stitcher / sql_template with `run_type: incremental`) makes the project incremental. Call this out — users who don't know their project is incremental are surprised by checkpoint behavior.
25	- Model dependency structure from `pb show models`.
26	- Latest run details: seq_no, output schema, output tables.
27	- Identity resolution health: stitching ratio, over-stitching candidates.
28	- Read-only graph lenses to offer: `pb audit id_stitcher` (interactive viewer), `pb show idstitcher-report` (pre/post-stitch counts, convergence, largest cluster), and `pb show entity-lookup -v <id_value>` (one entity's stitched IDs and features by any known ID).
29
30	## Incremental vs Discrete
31
32	A project becomes incremental the moment any entity_var declares `merge:`. Consequences worth surfacing:
33
34	- Each run produces a new checkpoint identified by `seq_no`; the previous checkpoint is the baseline, and a run computes the delta (rows since the baseline's `end_time`) and merges it in.
35	- Entity counts across seq_nos show growth, not run-over-run rebuild deltas — the latest seq_no's table is the cumulative view.
36	- For incremental projects, recommend a periodic discrete-vs-incremental side-by-side (a full `--rebase_incremental` run vs the incremental output) to catch silent drift. Migration and merge-correctness details live in `rudder-profiles-update` and `rudder-profiles-debug`.
37
38	## Output Style
39
40	Prefer a short explanatory narrative over a raw dump of YAML or SQL results. The summary should answer:
41
42	- What is this project trying to model?
43	- How do identities stitch together across sources?
44	- What features are being computed and from which inputs?
45	- Is the latest output healthy or are there red flags?
46	- What should the user investigate next?
47
48	## Health Indicators
49
50	When outputs are available, check these metrics via `run_query()`:
51
52	\| Metric \| What it reveals \| Red flag \|
53	\|--------\|----------------\|----------\|
54	\| Stitching ratio (raw IDs vs stitched entities) \| How much identity resolution is happening \| Ratio near 1.0 means stitching is not working \|
55	\| Over-stitching candidates \| Entities with unusually many raw IDs \| Single entity absorbing thousands of IDs \|
56	\| Feature NULL rates \| Data completeness \| NULL rate > 50% on a required feature \|
57	\| Entity count trend across runs \| Growth or regression \| Sudden large drops between seq_nos \|
58
59	## Guardrails
60
61	- This skill is read-only. Do not modify project files.
62	- If the project does not compile or key files are missing, say that clearly before interpreting outputs.
63	-

People who liked this also viewed

6 picks

Type