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

.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}

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

@@ -0,0 +1,110 @@
+'use client'
+
+import { useMemo, useRef, useState } from 'react'
+import { Check, Plus } from 'lucide-react'
+import { usePostHog } from 'posthog-js/react'
+import { Chip, toast } from '@/components/emcn'
+import { captureEvent } from '@/lib/posthog/client'
+import { SkillTile } from '@/app/workspace/[workspaceId]/components'
+import type { SuggestedSkill } from '@/blocks/types'
+import { useCreateSkill, useSkills } from '@/hooks/queries/skills'
+
+interface IntegrationSkillsSectionProps {
+ skills: readonly SuggestedSkill[]
+ workspaceId: string
+ integrationType: string
+}
+
+interface SkillRowProps {
+ skill: SuggestedSkill
+ added: boolean
+ pending: boolean
+ disabled: boolean
+ onAdd: () => void
+}
+
+function SkillRow({ skill, added, pending, disabled, onAdd }: SkillRowProps) {
+ return (
+ <div className='flex items-center gap-2.5 rounded-lg p-2'>
+ <SkillTile />
+ <div className='flex min-w-0 flex-1 flex-col'>
+ <span className='truncate text-[14px] text-[var(--text-body)]'>{skill.name}</span>
+ <span className='truncate text-[12px] text-[var(--text-muted)]'>{skill.description}</span>
+ </div>
+ {added ? (
+ <Chip variant='filled' leftIcon={Check} disabled flush>
+ Added
+ </Chip>
+ ) : (
+ <Chip variant='primary' leftIcon={Plus} onClick={onAdd} disabled={disabled} flush>
+ {pending ? 'Adding...' : 'Add'}
+ </Chip>
+ )}
+ </div>
+ )
+}
+
+/**
+ * Curated, research-backed skills for an integration. Each row adds the skill
+ * to the workspace via the same `useCreateSkill` mutation the Skills page uses;
+ * `useSkills` is the single source of truth for the "Added" state, so a skill
+ * removed elsewhere correctly reverts to "Add".
+ */
+export function IntegrationSkillsSection({
+ skills,
+ workspaceId,
+ integrationType,
+}: IntegrationSkillsSectionProps) {
+ const posthog = usePostHog()
+ const { data: existingSkills = [], isPending, isPlaceholderData } = useSkills(workspaceId)
+ const createSkill = useCreateSkill()
+ const skillsReady = !isPending && !isPlaceholderData
+ const [pendingNames, setPendingNames] = useState<ReadonlySet<string>>(new Set())
+ const inFlightRef = useRef<Set<string>>(new Set())
+
+ const existingNames = useMemo(() => new Set(existingSkills.map((s) => s.name)), [existingSkills])
+
+ const handleAdd = async (skill: SuggestedSkill, position: number) => {
+ if (inFlightRef.current.has(skill.name)) return
+ inFlightRef.current.add(skill.name)
+ setPendingNames((prev) => new Set(prev).add(skill.name))
+ try {
+ await createSkill.mutateAsync({ workspaceId, skill })
+ captureEvent(posthog, 'integration_skill_added', {
+ workspace_id: workspaceId,
+ integration_type: integrationType,
+ skill_name: skill.name,
+ position,
+ skill_count: skills.length,
+ })
+ } catch {
+ toast.error(`Failed to add "${skill.name}" — please try again`)
+ } finally {
+ inFlightRef.current.delete(skill.name)
+ setPendingNames((prev) => {
+ const next = new Set(prev)
+ next.delete(skill.name)
+ return next
+ })
+ }
+ }
+
+ return (
+ <section className='flex flex-col'>
+ <span className='pl-0.5 text-[var(--text-muted)] text-small'>Skills</span>
+ <div className='mt-[9px] mb-3 h-px bg-[var(--border)]' />
+ <div className='-mx-2 flex flex-col gap-y-0.5'>
+ {skills.map((skill, index) => (
+ <SkillRow
+ key={skill.name}
+ skill={skill}
+ added={skillsReady && existingNames.has(skill.name)}
+ pending={pendingNames.has(skill.name)}
+ disabled={pendingNames.has(skill.name) || !skillsReady}
+ onAdd={() => handleAdd(skill, index)}
+ />
+ ))}
+ </div>
+ </section>
+ )
+}

apps/sim/app/workspace/[workspaceId]/skills/skills.tsx

@@ -14,7 +14,7 @@ import {
  ChipModalHeader,
  Search,
 } from '@/components/emcn'
-import { AgentSkillsIcon } from '@/components/icons'
+import { SkillTile } from '@/app/workspace/[workspaceId]/components'
 import { IntegrationTabsHeader } from '@/app/workspace/[workspaceId]/integrations/components/integration-tabs-header'
 import { ShowcaseWithExplore } from '@/app/workspace/[workspaceId]/integrations/components/showcase-with-explore'
 import { SkillModal } from '@/app/workspace/[workspaceId]/skills/components/skill-modal'
@@ -29,16 +29,6 @@ const logger = createLogger('SkillsSettings')
 
 const SKILLS_LABEL = 'Skills'
 
-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>
- )
-}
-
 interface SkillItemProps {
  name: string
  description: string

apps/sim/blocks/AGENTS.md

@@ -10,3 +10,4 @@ These rules apply to block definitions under `apps/sim/blocks/**`.
 - Put type coercion in `tools.config.params`, never in `tools.config.tool`.
 - When supporting file inputs, follow the basic/advanced pattern and normalize with `normalizeFileInput`.
 - Keep block outputs aligned with what the referenced tools actually return.
+- `{Service}BlockMeta.skills` (curated, one-click-add agent skills shown on the integration detail page) must be grounded in operations the block exposes via `tools.access` and derived from real, popular use cases found online — web-search and source each one; never invent or hallucinate skills.