feat(integrations): suggest curated skills per integration with one-click add (#4912)

* feat(integrations): suggest curated skills per integration with one-click add

Curate research-backed, capability-grounded skills for every catalog
integration and surface them on the integration detail page. Each skill
maps to operations the block actually supports and can be added to the
workspace in one click; track adds in PostHog.

- Add SuggestedSkill type + skills field on BlockMeta; populate skills
  for all 193 catalog integrations (3 audit passes for grounding/sourcing)
- getSuggestedSkillsForBlock() with versioned-type (e.g. notion_v2) base fallback
- Skills section on the integration detail page with add/added states
- integration_skill_added PostHog event with workspace/integration metadata

* fix(integrations): flip suggested-skill row to Added immediately after add

The row derived Added state solely from the useSkills cache, so between a
successful create and the list refetch the row still showed Add and could
be clicked again, hitting the server duplicate-name check. Track added
names in local state so the row reflects the add immediately.

* fix(integrations): harden suggested-skill add flow; document skill authoring

Address PR review feedback on the suggested-skills section:
- Make useSkills the single source of truth for Added state by writing the
  created skill into the React Query cache onSuccess (fixes stale Added that
  survived a delete, and the lag that allowed a duplicate click)
- Track in-flight adds in a Set so concurrent adds keep independent pending
  state and cannot be double-submitted
- Surface failures with toast.error instead of swallowing the rejection
- Extract the duplicated SkillTile into a shared workspace component

Also document the new BlockMeta.skills field in the add-block and
validate-integration skills (+ blocks AGENTS.md): skills must be grounded in
the block's tools.access and sourced from real online use cases, never invented.

* fix(integrations): synchronous in-flight guard for skill add; align cursor docs

- Guard handleAdd with a ref so two rapid clicks cannot both fire a create
  before the disabled state re-renders (pendingNames is async)
- Fold the create-cache-merge rationale into the hook's TSDoc and drop
  non-TSDoc inline comments to match the repo convention
- Align .cursor add-block/validate-integration command docs with the newer
  .claude/.agents versions: BlockMeta section + skills authoring/validation
  guidance (grounded in tools.access, sourced from real online use cases)

* fix(integrations): gate skill Add/Added on authoritative workspace skills

useSkills uses keepPreviousData, so during initial load or a workspace switch
the list could be empty or a prior workspace's placeholder — making rows show
a misleading Add (duplicate-submittable) or a false Added. Derive skillsReady
from !isPending && !isPlaceholderData, only mark Added when ready, and disable
Add until the current workspace's list has loaded.

* chore(integrations): drop local-variable comments in skills section

Keep to the repo's TSDoc-on-declarations convention — the in-flight guard and
skillsReady derivation are self-evident from naming.

Author: waleedlatif1

.agents/skills/add-block/SKILL.md

@@ -651,6 +651,14 @@ export const {Service}BlockMeta = {
       alsoIntegrations: ['slack'],      // Other blocks referenced in the prompt (optional)
     },
   ],
+  skills: [                             // Optional but strongly encouraged
+    {
+      name: 'summarize-thread',         // kebab-case, becomes the created skill's name
+      description: 'One line: what it does and when to use it.',
+      content:
+        '# Summarize Thread\n\n...\n\n## Steps\n1. ...\n\n## Output\n...',  // markdown
+    },
+  ],
 } as const satisfies BlockMeta
 ```
 
@@ -665,6 +673,16 @@ export const {Service}BlockMeta = {
 - **`alsoIntegrations`** names other block types (e.g. `'slack'`, `'linear'`) referenced in the template prompt — helps the catalog surface this template when those blocks are selected
 - Place the export **after** the main `{Service}Block` export, at the very bottom of the file
 
+#### `skills` — curated, ready-to-add agent skills
+
+`skills` is an optional array of `SuggestedSkill` (`{ name, description, content }`) shown on the integration's detail page; users click **Add** to create the skill in their workspace. Aim for 3–5 skills for mainstream services, 2–3 for niche/low-level ones.
+
+- **`name`** — kebab-case, lowercase letters/numbers/hyphens, ≤ 64 chars, unique within the integration, verb-led (e.g. `summarize-thread`).
+- **`description`** — one line, ≤ 1024 chars: what it does and when to use it.
+- **`content`** — markdown instructions for the agent (literal `\n` for newlines): a `# Title`, then `## Steps` and an output/guidance section. Keep ~600–2000 chars.
+- **Ground every skill in operations the block actually exposes.** Cross-check each skill's steps against the block's `tools.access` list — never describe an action the integration cannot perform (e.g. "receive messages" when the block only sends).
+- **Skills MUST be derived from real, popular use cases found online — never invented.** Before adding a skill, web-search the service's documented use cases (vendor use-case/solutions pages, official docs describing the workflow, reputable "top automations for X" articles). If you cannot source a use case as something people genuinely do with the service, do not add it. Do not hallucinate skills.
+
 ### Register in the blocksMeta object
 
 After adding `{Service}BlockMeta` to the block file, register it in `apps/sim/blocks/registry.ts`:
@@ -888,6 +906,7 @@ All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MU
 - [ ] Outputs match tool outputs
 - [ ] Block registered in `registry.ts` blocks object (alphabetically)
 - [ ] `{Service}BlockMeta` exported at bottom of block file with `tags` and `templates`
+- [ ] `skills` added to `{Service}BlockMeta`, each grounded in the block's `tools.access` and derived from a real online-sourced use case (not invented)
 - [ ] `BlockMeta` imported from `@/blocks/types` alongside `BlockConfig`
 - [ ] Block meta registered in `registry.ts` blocksMeta object (alphabetically)
 - [ ] If icon missing: asked user to provide SVG

.agents/skills/validate-integration/SKILL.md

@@ -207,6 +207,12 @@ For **each tool** in `tools.access`:
 - [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
 - [ ] Block is registered in `blocks/registry.ts` alphabetically
 
+### BlockMeta Skills (catalog)
+- [ ] `{Service}BlockMeta.skills` is present (3–5 for mainstream services, 2–3 for niche/low-level)
+- [ ] **Every skill is grounded** — its steps only use operations the block exposes in `tools.access`; flag any skill that implies an unsupported action (e.g. "receive messages" when the block only sends)
+- [ ] **Every skill is real, not hallucinated** — web-search the service and confirm each skill maps to a popular use case attested online (vendor use-case/solutions pages, official docs describing the workflow, reputable "top automations for X" articles). Rewrite or remove any skill you cannot source as something people genuinely do with the service.
+- [ ] Each skill has a kebab-case `name` (≤64 chars, unique), a one-line `description`, and markdown `content` with `# Title` + `## Steps` + an output/guidance section
+
 ### Block Inputs
 - [ ] `inputs` section lists all subBlock params that the block accepts
 - [ ] Input types match the subBlock types

.claude/commands/add-block.md

@@ -807,11 +807,25 @@ export const {Service}BlockMeta = {
     },
     // ... at least 6 more
   ],
+  skills: [                                // SuggestedSkill[] — 3–5 mainstream, 2–3 niche
+    {
+      name: 'summarize-thread',            // kebab-case, ≤64 chars, unique, verb-led
+      description: 'One line: what it does and when to use it.',  // ≤1024 chars
+      content:
+        '# Summarize Thread\n\n...\n\n## Steps\n1. ...\n\n## Output\n...',  // markdown
+    },
+    // ... more
+  ],
 } as const satisfies BlockMeta
 ```
 
 Derive templates from the service's real use cases. Each prompt should name a concrete trigger, transformation, and output — not a generic description of what the service does.
 
+`skills` are curated, ready-to-add agent skills shown on the integration's detail page (users click **Add** to create them in their workspace). Two hard rules:
+
+- **Ground every skill in operations the block actually exposes** — cross-check each skill's steps against `tools.access`. Never describe an action the integration cannot perform.
+- **Derive skills from real, popular use cases found online — never invent them.** Web-search the service's documented use cases (vendor use-case/solutions pages, official docs describing the workflow, reputable "top automations for X" articles) and only add a skill you can source as something people genuinely do with the service. Do not hallucinate skills.
+
 ## Checklist Before Finishing
 
 - [ ] `integrationType` is set to the correct `IntegrationType` enum value
@@ -831,6 +845,7 @@ Derive templates from the service's real use cases. Each prompt should name a co
 - [ ] Optional/rarely-used fields set to `mode: 'advanced'`
 - [ ] Timestamps and complex inputs have `wandConfig` enabled
 - [ ] Exported `{Service}BlockMeta` with at least 7 templates
+- [ ] `skills` added to `{Service}BlockMeta`, each grounded in `tools.access` and sourced from a real online use case (not invented)
 
 ## Final Validation (Required)
 

.claude/commands/validate-integration.md

@@ -197,6 +197,8 @@ For **each tool** in `tools.access`:
 - [ ] Has at least 7 templates, each with `icon`, `title`, `prompt`, `modules`, `category`, and `tags`
 - [ ] Prompts describe concrete use cases, not generic descriptions of what the service does
 - [ ] `alsoIntegrations` is set on any template whose prompt references another service
+- [ ] `skills` present (3–5 mainstream, 2–3 niche), each grounded in `tools.access` — flag any skill implying an unsupported action
+- [ ] **Each skill is real, not hallucinated** — web-search and confirm it maps to a popular use case attested online (vendor use-case pages, official docs describing the workflow, reputable "top automations" articles); rewrite/remove any you cannot source
 
 ### Block Inputs
 - [ ] `inputs` section lists all subBlock params that the block accepts

.cursor/commands/add-block.md

@@ -793,6 +793,47 @@ Use `wandConfig` for fields that are hard to fill out manually, such as timestam
 
 All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MUST use `snake_case` (e.g., `x_create_tweet`, `slack_send_message`). Never use camelCase or PascalCase.
 
+## BlockMeta (Required)
+
+Every block file must export a `{Service}BlockMeta` alongside the block — **minimum 7 templates**. Look at existing examples in `apps/sim/blocks/blocks/` (e.g. `browser_use.ts`, `google_sheets.ts`) for the pattern.
+
+```typescript
+import type { BlockMeta } from '@/blocks/types'
+
+export const {Service}BlockMeta = {
+  tags: ['tag1', 'tag2'],                  // IntegrationTag[]
+  templates: [
+    {
+      icon: {Service}Icon,
+      title: '{Service} <use-case>',        // 2–5 words
+      prompt: 'Build a workflow that...',   // specific use case, 1–3 sentences
+      modules: ['agent', 'workflows'],      // 'agent' | 'workflows' | 'tables' | 'files' | 'scheduled' | 'knowledge-base'
+      category: 'operations',              // 'operations' | 'marketing' | 'sales' | 'engineering' | 'productivity' | 'support' | 'popular'
+      tags: ['automation'],
+      alsoIntegrations: ['slack'],         // optional — other block IDs referenced in the prompt
+      featured: true,                      // optional
+    },
+    // ... at least 6 more
+  ],
+  skills: [                                // SuggestedSkill[] — 3–5 mainstream, 2–3 niche
+    {
+      name: 'summarize-thread',            // kebab-case, ≤64 chars, unique, verb-led
+      description: 'One line: what it does and when to use it.',  // ≤1024 chars
+      content:
+        '# Summarize Thread\n\n...\n\n## Steps\n1. ...\n\n## Output\n...',  // markdown
+    },
+    // ... more
+  ],
+} as const satisfies BlockMeta
+```
+
+Derive templates from the service's real use cases. Each prompt should name a concrete trigger, transformation, and output — not a generic description of what the service does.
+
+`skills` are curated, ready-to-add agent skills shown on the integration's detail page (users click **Add** to create them in their workspace). Two hard rules:
+
+- **Ground every skill in operations the block actually exposes** — cross-check each skill's steps against `tools.access`. Never describe an action the integration cannot perform.
+- **Derive skills from real, popular use cases found online — never invent them.** Web-search the service's documented use cases (vendor use-case/solutions pages, official docs describing the workflow, reputable "top automations for X" articles) and only add a skill you can source as something people genuinely do with the service. Do not hallucinate skills.
+
 ## Checklist Before Finishing
 
 - [ ] `integrationType` is set to the correct `IntegrationType` enum value
@@ -811,6 +852,8 @@ All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MU
 - [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
 - [ ] Optional/rarely-used fields set to `mode: 'advanced'`
 - [ ] Timestamps and complex inputs have `wandConfig` enabled
+- [ ] Exported `{Service}BlockMeta` with at least 7 templates
+- [ ] `skills` added to `{Service}BlockMeta`, each grounded in `tools.access` and sourced from a real online use case (not invented)
 
 ## Final Validation (Required)
 

.cursor/commands/validate-integration.md

@@ -187,6 +187,14 @@ For **each tool** in `tools.access`:
 - [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
 - [ ] Block is registered in `blocks/registry.ts` alphabetically
 
+### BlockMeta
+- [ ] `{Service}BlockMeta` is exported in the same file as the block
+- [ ] Has at least 7 templates, each with `icon`, `title`, `prompt`, `modules`, `category`, and `tags`
+- [ ] Prompts describe concrete use cases, not generic descriptions of what the service does
+- [ ] `alsoIntegrations` is set on any template whose prompt references another service
+- [ ] `skills` present (3–5 mainstream, 2–3 niche), each grounded in `tools.access` — flag any skill implying an unsupported action
+- [ ] **Each skill is real, not hallucinated** — web-search and confirm it maps to a popular use case attested online (vendor use-case pages, official docs describing the workflow, reputable "top automations" articles); rewrite/remove any you cannot source
+
 ### Block Inputs
 - [ ] `inputs` section lists all subBlock params that the block accepts
 - [ ] Input types match the subBlock types

apps/sim/app/workspace/[workspaceId]/components/index.ts

@@ -27,3 +27,4 @@ export type {
   SelectableConfig,
 } from './resource/resource'
 export { EMPTY_CELL_PLACEHOLDER, Resource, ResourceTable } from './resource/resource'
+export { SkillTile } from './skill-tile'

apps/sim/app/workspace/[workspaceId]/components/skill-tile/index.ts

@@ -0,0 +1 @@
+export { SkillTile } from './skill-tile'

apps/sim/app/workspace/[workspaceId]/components/skill-tile/skill-tile.tsx

@@ -0,0 +1,16 @@
+import { AgentSkillsIcon } from '@/components/icons'
+
+/**
+ * Square tile bearing the agent-skills glyph. Shared chrome for any surface
+ * that lists a skill (the Skills page and integration detail pages) so the two
+ * do not drift.
+ */
+export function SkillTile() {
+  return (
+    <div className='size-9 flex-shrink-0'>
+      <div className='flex size-full items-center justify-center rounded-xl border border-[var(--border-1)] bg-[var(--surface-4)] dark:bg-[var(--surface-5)]'>
+        <AgentSkillsIcon className='size-5 text-[var(--text-icon)]' />
+      </div>
+    </div>
+  )
+}

apps/sim/app/workspace/[workspaceId]/integrations/[block]/integration-block-detail.tsx

@@ -14,14 +14,19 @@ import {
 } from '@/lib/integrations'
 import { getServiceConfigByProviderId } from '@/lib/oauth'
 import { ConnectOAuthModal } from '@/app/workspace/[workspaceId]/components/connect-oauth-modal'
+import { IntegrationSkillsSection } from '@/app/workspace/[workspaceId]/integrations/[block]/integration-skills-section'
 import { ConnectServiceAccountModal } from '@/app/workspace/[workspaceId]/integrations/components/connect-service-account-modal'
 import { IntegrationSection } from '@/app/workspace/[workspaceId]/integrations/components/integration-section'
 import { IntegrationTile } from '@/app/workspace/[workspaceId]/integrations/components/integrations-showcase'
 import {
   CONNECT_MODE,
   CONNECT_QUERY_PARAM,
 } from '@/app/workspace/[workspaceId]/integrations/connect-route'
-import { getTemplatesForBlock, type ScopedBlockTemplate } from '@/blocks/registry'
+import {
+  getSuggestedSkillsForBlock,
+  getTemplatesForBlock,
+  type ScopedBlockTemplate,
+} from '@/blocks/registry'
 import { useWorkspaceCredentials } from '@/hooks/queries/credentials'
 import { useOAuthReturnRouter } from '@/hooks/use-oauth-return'
 
@@ -46,6 +51,7 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
   const searchParams = useSearchParams()
   const Icon = blockTypeToIconMap[integration.type]
   const matchingTemplates = getTemplatesForBlock(integration.type)
+  const suggestedSkills = getSuggestedSkillsForBlock(integration.type)
   const oauthService = resolveOAuthServiceForIntegration(integration)
   const [oauthOpen, setOAuthOpen] = useState(false)
 
@@ -210,6 +216,14 @@ export function IntegrationBlockDetail({ integration, workspaceId }: Integration
             </IntegrationSection>
           )}
 
+          {suggestedSkills.length > 0 && (
+            <IntegrationSkillsSection
+              skills={suggestedSkills}
+              workspaceId={workspaceId}
+              integrationType={integration.type}
+            />
+          )}
+
           {matchingTemplates.length > 0 && (
             <TemplatesSection
               integration={integration}