{"id":"b97111ed-ee27-4e5e-9342-f5e4725b72dc","shortId":"6XdJ4j","kind":"skill","title":"creating-insights","tagline":"Creates discoveries with insights through the approval workflow. Use when generating findings, creating visualizations, or saving and sharing analysis results.","description":"# Creating Insights\n\n## Quick Start\n\nTo create an insight:\n1. Analyze data to identify a finding\n2. Choose the appropriate insight type (SQL, Semantic, Segmentation, Funnel, Retention) or create a text-only FYI discovery\n3. Preview the insight to validate\n4. Create the discovery with visualization\n\n## When to Use This Skill\n\n- Found a notable pattern or anomaly\n- User asks to save or share findings\n- Creating a visualization from analysis\n- Surfacing automated discoveries\n- Generating reports or dashboards content\n\n## Insight Types\n\n| Type | Use Case | Visualization |\n|------|----------|---------------|\n| SQL | Custom query results | Yes |\n| Semantic | Metrics from semantic layer | Yes |\n| Segmentation | Event metrics over time, compared across property-based segments | Yes |\n| Funnel | Conversion analysis | Yes |\n| Retention | Do users come back after an event? | Yes |\n| FYI | Informational findings | No |\n\n## Core Workflow\n\n### Step 1: Identify the Finding\n\nBefore creating an insight:\n- What is the key observation?\n- Is it significant enough to share?\n- What action should it drive?\n\n### Step 2: Choose Insight Type\n\nBefore choosing, triage through these questions:\n\n1. **Does this need a visualization?** No → **FYI**. Yes → continue.\n2. **Is the metric available in the semantic layer?** Yes → **Semantic**. Not sure → check the model first.\n3. **Is the finding about sequential user behavior** (steps, conversion, drop-off)? Yes → **Funnel**.\n4. **Is the finding about whether users come back** after a starting event? Yes → **Retention**.\n5. **Is the finding about comparing event metrics across cohorts or property breakdowns** (without ordered step dependencies)? Yes → **Segmentation**.\n6. **Does it require custom joins, calculations, or raw data not covered above?** Yes → **SQL**.\n\nSelect based on the analysis:\n- **Funnel Insight**: Sequential steps, progression, conversion, drop-off between stages\n- **Retention Insight**: Whether users return after a starting event (start event → returning event over time)\n- **Semantic Insight**: Standard metrics from semantic models, trends, breakdowns\n- **SQL Insight**: Custom query with specific logic, joins, calculations not in the semantic layer\n- **Segmentation Insight**: Event analysis over time with breakdowns by event, user, or session properties to compare segment behavior\n- **FYI Discovery**: Text-only observations, no visualization needed\n\nSee the [`deciding-actions`](../deciding-actions/SKILL.md) skill for the full decision matrix and disambiguation rules.\n\n### Step 3: Preview and Validate\n\nAlways preview before creating:\n- Verify data is correct\n- Check visualization renders properly\n- Ensure timeframe is appropriate\n\n### Step 4: Create Discovery\n\nCreate with:\n- Clear, actionable title\n- Concise description\n- Appropriate visualization\n- Relevant metadata\n\n## Discovery States\n\nDiscoveries flow through an approval workflow:\n\n```\npending  -->  approved | rejected\n```\n\n| State      | Description          |\n|------------|----------------------|\n| `pending`  | Awaiting review      |\n| `approved` | Approved             |\n| `rejected` | Rejected             |\n\nBoth transitions are reversible: an approved discovery can later be rejected, and a rejected one can later be approved.\n\n## Creating SQL Insights\n\nFor custom query-based insights:\n\n```\n1. Write and validate SQL query\n2. Preview SQL insight with the query\n3. Choose appropriate visualization\n4. Create discovery with insight\n```\n\n### SQL Insight Parameters\n\n- `query`: The SQL query\n- `connection_slug`: Which connection to query\n- `visualization`: Chart type (Line, Bar, Table, etc.)\n\n### Best Practices\n\n- Use CTEs for readability\n- Include time filters\n- Limit result size for performance\n- Add column aliases for display\n\n## Creating Semantic Insights\n\nFor metrics from the semantic layer:\n\n```\n1. Select source and measures\n2. Add dimensions for grouping\n3. Apply filters\n4. Preview and validate\n5. Create discovery\n```\n\n### Semantic Insight Parameters\n\n- `source_slug`: Semantic source to query\n- `measures`: List of measures to aggregate\n- `dimensions`: Dimensions for grouping\n- `filters`: Filter conditions\n- `visualization`: Chart type\n\n## Creating Segmentation Insights\n\nFor segment and cohort comparisons:\n\n```\n1. Select the events/metrics to analyze\n2. Choose aggregation (count, unique users, sum, average)\n3. Add breakdowns by event, user, or session properties\n4. Set filters and time range\n5. Preview segment results\n6. Create discovery\n```\n\n### Segmentation Parameters\n\n- `event_definitions`: Which events to analyze\n- `aggregation_mode`: How to aggregate results (count, unique users, sum, average)\n- `breakdowns`: Properties used to compare segments\n- `filters`: Segment/filter criteria\n- `timeframe`: Analysis period\n\n## Creating Funnel Insights\n\nFor conversion analysis:\n\n```\n1. Define funnel steps (events)\n2. Set conversion window\n3. Choose ordering (strict/any)\n4. Preview funnel metrics\n5. Create discovery\n```\n\n### Funnel Parameters\n\n- `steps`: Ordered list of events\n- `conversion_window`: Time allowed between steps\n- `ordering`: Strict sequence or any order\n\n## Creating Retention Insights\n\nFor analyzing whether users come back after a starting event:\n\n```\n1. Define the start event\n2. Define the returning event\n3. Set time range\n4. Preview retention results\n5. Create discovery\n```\n\n### Retention Parameters\n\n- `start_event`: The initial event that begins the retention window\n- `returning_event`: The event that counts as a return\n- `timeframe`: Analysis period\n\n> **Note:** Retention can be previewed via the `preview_insight` MCP tool but is not currently exposed for creation via MCP (no `create_retention_insight` tool).\n\n## Creating FYI Discoveries\n\nFor informational findings without visualization:\n\n```\n1. Write clear title\n2. Provide detailed description\n3. Add supporting context\n4. Create FYI discovery\n```\n\n### FYI Use Cases\n\n- Text-based observations\n- Recommendations\n- Warnings or alerts\n- Context for other findings\n\n## Writing Effective Titles\n\nGood titles are:\n- **Actionable**: \"Revenue dropped 15% last week\"\n- **Specific**: Include key metric and timeframe\n- **Concise**: Under 100 characters\n\n### Examples\n\n| Good | Bad |\n|------|-----|\n| \"Mobile conversion rate dropped 20% in Q4\" | \"Conversion issue\" |\n| \"New users from organic search up 3x\" | \"Traffic increase\" |\n| \"Cart abandonment spikes on weekends\" | \"Weekend pattern\" |\n\n## Writing Descriptions\n\n**Descriptions must be 200 characters or less.**\n\nInclude:\n- **What**: The key observation\n- **Context**: Comparison or benchmark\n- **Impact**: Business significance\n- **Recommendation**: Suggested action (if space permits)\n\n### Example\n\n> Mobile conversion dropped 20% (3.2% to 2.5%) last month, coinciding with the March 1st checkout redesign. Consider A/B testing the previous flow.\n\n## Visualization Selection\n\n| Data Type | Recommended |\n|-----------|-------------|\n| Time series | Line, Area |\n| Comparison | Bar, BarList |\n| Distribution | Pie, Bar |\n| Single metric | Metric |\n| Detailed data | Table |\n| Funnel | Funnel (built-in) |\n| Retention | Retention (built-in) |\n\n## Common Pitfalls\n\n- Creating insights without clear value\n- Vague titles that don't convey the finding\n- Missing context in descriptions\n- Wrong visualization for data type\n- Not previewing before creating\n- Creating duplicates of existing insights\n\n## Troubleshooting Rejected Discoveries\n\n**If `rejected`:**\n- Finding may not be actionable enough\n- Consider: Is the insight significant? Is timing relevant?\n- Refine: strengthen the \"so what\" - why should they care?\n- Add clearer recommendation or next step\n- Parse the free-text `reason` on the feedback for specific issues\n\n**Common rejection reasons and fixes:**\n\n| Reason | Fix |\n|--------|-----|\n| \"Already known\" | Search for existing insights before creating |\n| \"Not actionable\" | Add specific recommendation |\n| \"Too vague\" | Include concrete numbers and timeframes |\n| \"Wrong audience\" | Check if insight matches user's domain |\n| \"Stale data\" | Verify timeframe is current |\n\n## Reference Files\n\n- [SQL insights](references/sql-insights.md)\n- [Semantic insights](references/semantic-insights.md)\n- [Segmentation insights](references/segmentation-insights.md)\n- [Funnel insights](references/funnel-insights.md)\n- [FYI discoveries](references/fyi-discoveries.md)","tags":["creating","insights","skills","altertable-ai","agent-skills","ai-agents","altertable"],"capabilities":["skill","source-altertable-ai","skill-creating-insights","topic-agent-skills","topic-ai-agents","topic-altertable"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/altertable-ai/skills/creating-insights","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add altertable-ai/skills","source_repo":"https://github.com/altertable-ai/skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (8,370 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:19.897Z","embedding":null,"createdAt":"2026-05-18T13:21:54.574Z","updatedAt":"2026-05-18T19:14:19.897Z","lastSeenAt":"2026-05-18T19:14:19.897Z","tsv":"'/deciding-actions/skill.md':362 '1':32,150,185,456,526,579,652,704,782 '100':833 '15':822 '1st':904 '2':39,175,195,462,531,585,657,709,786 '2.5':897 '20':842,894 '200':868 '3':58,212,373,469,536,593,661,714,790 '3.2':895 '3x':853 '4':64,227,394,473,539,602,665,718,794 '5':242,543,608,669,722 '6':261,612 'a/b':908 'abandon':857 'across':124,250 'action':170,361,400,819,886,986,1039 'add':512,532,594,791,1005,1040 'aggreg':560,587,623,627 'alert':808 'alias':514 'allow':682 'alreadi':1030 'alway':377 'analysi':22,92,132,280,333,644,651,747 'analyz':33,584,622,695 'anomali':80 'appli':537 'appropri':42,392,404,471 'approv':10,414,417,424,425,433,446 'area':921 'ask':82 'audienc':1051 'autom':94 'avail':199 'averag':592,633 'await':422 'back':138,235,699 'bad':837 'bar':495,923,927 'barlist':924 'base':127,277,454,803 'begin':733 'behavior':219,347 'benchmark':880 'best':498 'breakdown':254,315,337,595,634 'built':937,942 'built-in':936,941 'busi':882 'calcul':267,324 'care':1004 'cart':856 'case':105,800 'charact':834,869 'chart':492,569 'check':208,385,1052 'checkout':905 'choos':40,176,180,470,586,662 'clear':399,784,949 'clearer':1006 'cohort':251,577 'coincid':900 'column':513 'come':137,234,698 'common':944,1023 'compar':123,247,345,638 'comparison':578,878,922 'concis':402,831 'concret':1046 'condit':567 'connect':485,488 'consid':907,988 'content':100 'context':793,809,877,960 'continu':194 'convers':131,221,286,650,659,679,839,845,892 'convey':956 'core':147 'correct':384 'count':588,629,742 'cover':272 'creat':2,4,16,24,29,51,65,88,155,380,395,397,447,474,517,544,571,613,646,670,691,723,770,774,795,946,971,972,1037 'creating-insight':1 'creation':766 'criteria':642 'ctes':501 'current':763,1064 'custom':108,265,318,451 'dashboard':99 'data':34,270,382,915,932,966,1060 'decid':360 'deciding-act':359 'decis':367 'defin':653,705,710 'definit':618 'depend':258 'descript':403,420,789,864,865,962 'detail':788,931 'dimens':533,561,562 'disambigu':370 'discoveri':5,57,67,95,349,396,408,410,434,475,545,614,671,724,776,797,979,1080 'display':516 'distribut':925 'domain':1058 'drive':173 'drop':223,288,821,841,893 'drop-off':222,287 'duplic':973 'effect':814 'enough':166,987 'ensur':389 'etc':497 'event':119,141,239,248,300,302,304,332,339,597,617,620,656,678,703,708,713,728,731,738,740 'events/metrics':582 'exampl':835,890 'exist':975,1034 'expos':764 'feedback':1019 'file':1066 'filter':506,538,565,566,604,640 'find':15,38,87,145,153,215,230,245,779,812,958,982 'first':211 'fix':1027,1029 'flow':411,912 'found':75 'free':1014 'free-text':1013 'full':366 'funnel':48,130,226,281,647,654,667,672,934,935,1076 'fyi':56,143,192,348,775,796,798,1079 'generat':14,96 'good':816,836 'group':535,564 'identifi':36,151 'impact':881 'includ':504,826,872,1045 'increas':855 'inform':144,778 'initi':730 'insight':3,7,25,31,43,61,101,157,177,282,293,308,317,331,449,455,465,477,479,519,547,573,648,693,757,772,947,976,991,1035,1054,1068,1071,1074,1077 'issu':846,1022 'join':266,323 'key':161,827,875 'known':1031 'last':823,898 'later':436,444 'layer':116,203,329,525 'less':871 'limit':507 'line':494,920 'list':556,676 'logic':322 'march':903 'match':1055 'matrix':368 'may':983 'mcp':758,768 'measur':530,555,558 'metadata':407 'metric':113,120,198,249,310,521,668,828,929,930 'miss':959 'mobil':838,891 'mode':624 'model':210,313 'month':899 'must':866 'need':188,356 'new':847 'next':1009 'notabl':77 'note':749 'number':1047 'observ':162,353,804,876 'one':442 'order':256,663,675,685,690 'organ':850 'paramet':480,548,616,673,726 'pars':1011 'pattern':78,862 'pend':416,421 'perform':511 'period':645,748 'permit':889 'pie':926 'pitfal':945 'practic':499 'preview':59,374,378,463,540,609,666,719,753,756,969 'previous':911 'progress':285 'proper':388 'properti':126,253,343,601,635 'property-bas':125 'provid':787 'q4':844 'queri':109,319,453,461,468,481,484,490,554 'query-bas':452 'question':184 'quick':26 'rang':607,717 'rate':840 'raw':269 'readabl':503 'reason':1016,1025,1028 'recommend':805,884,917,1007,1042 'redesign':906 'refer':1065 'references/funnel-insights.md':1078 'references/fyi-discoveries.md':1081 'references/segmentation-insights.md':1075 'references/semantic-insights.md':1072 'references/sql-insights.md':1069 'refin':996 'reject':418,426,427,438,441,978,981,1024 'relev':406,995 'render':387 'report':97 'requir':264 'result':23,110,508,611,628,721 'retent':49,134,241,292,692,720,725,735,750,771,939,940 'return':296,303,712,737,745 'revenu':820 'revers':431 'review':423 'rule':371 'save':19,84 'search':851,1032 'see':357 'segment':47,118,128,260,330,346,572,575,610,615,639,1073 'segment/filter':641 'select':276,527,580,914 'semant':46,112,115,202,205,307,312,328,518,524,546,551,1070 'sequenc':687 'sequenti':217,283 'seri':919 'session':342,600 'set':603,658,715 'share':21,86,168 'signific':165,883,992 'singl':928 'size':509 'skill':74,363 'skill-creating-insights' 'slug':486,550 'sourc':528,549,552 'source-altertable-ai' 'space':888 'specif':321,825,1021,1041 'spike':858 'sql':45,107,275,316,448,460,464,478,483,1067 'stage':291 'stale':1059 'standard':309 'start':27,238,299,301,702,707,727 'state':409,419 'step':149,174,220,257,284,372,393,655,674,684,1010 'strengthen':997 'strict':686 'strict/any':664 'suggest':885 'sum':591,632 'support':792 'sure':207 'surfac':93 'tabl':496,933 'test':909 'text':54,351,802,1015 'text-bas':801 'text-on':53,350 'time':122,306,335,505,606,681,716,918,994 'timefram':390,643,746,830,1049,1062 'titl':401,785,815,817,952 'tool':759,773 'topic-agent-skills' 'topic-ai-agents' 'topic-altertable' 'traffic':854 'transit':429 'trend':314 'triag':181 'troubleshoot':977 'type':44,102,103,178,493,570,916,967 'uniqu':589,630 'use':12,72,104,500,636,799 'user':81,136,218,233,295,340,590,598,631,697,848,1056 'vagu':951,1044 'valid':63,376,459,542 'valu':950 'verifi':381,1061 'via':754,767 'visual':17,69,90,106,190,355,386,405,472,491,568,781,913,964 'warn':806 'week':824 'weekend':860,861 'whether':232,294,696 'window':660,680,736 'without':255,780,948 'workflow':11,148,415 'write':457,783,813,863 'wrong':963,1050 'yes':111,117,129,133,142,193,204,225,240,259,274","prices":[{"id":"77feada3-58a2-4b2c-8e41-76e077a956ac","listingId":"b97111ed-ee27-4e5e-9342-f5e4725b72dc","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"altertable-ai","category":"skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:54.574Z"}],"sources":[{"listingId":"b97111ed-ee27-4e5e-9342-f5e4725b72dc","source":"github","sourceId":"altertable-ai/skills/creating-insights","sourceUrl":"https://github.com/altertable-ai/skills/tree/main/skills/creating-insights","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:54.574Z","lastSeenAt":"2026-05-18T19:14:19.897Z"}],"details":{"listingId":"b97111ed-ee27-4e5e-9342-f5e4725b72dc","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"altertable-ai","slug":"creating-insights","github":{"repo":"altertable-ai/skills","stars":7,"topics":["agent-skills","ai-agents","altertable"],"license":"mit","html_url":"https://github.com/altertable-ai/skills","pushed_at":"2026-05-14T10:34:10Z","description":"Agent Skills for Altertable","skill_md_sha":"fa93123f6048ef3ae53a71f7a60d46e0890ecc46","skill_md_path":"skills/creating-insights/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/altertable-ai/skills/tree/main/skills/creating-insights"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"creating-insights","description":"Creates discoveries with insights through the approval workflow. Use when generating findings, creating visualizations, or saving and sharing analysis results.","compatibility":"Requires Altertable MCP server"},"skills_sh_url":"https://skills.sh/altertable-ai/skills/creating-insights"},"updatedAt":"2026-05-18T19:14:19.897Z"}}