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.

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/validate-integration.md

@@ -186,6 +186,7 @@ For **each tool** in `tools.access`:
 - [ ] `icon` references the correct icon component from `@/components/icons`
 - [ ] `authMode` is set correctly (`AuthMode.OAuth` or `AuthMode.ApiKey`)
 - [ ] Block is registered in `blocks/registry.ts` alphabetically
+- [ ] `{Service}BlockMeta.skills` present (3–5 mainstream, 2–3 niche), each grounded in `tools.access` and confirmed via web search to be a real, popular use case (not hallucinated) — rewrite/remove any you cannot source
 
 ### Block Inputs
 - [ ] `inputs` section lists all subBlock params that the block accepts

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-skills-section.tsx

@@ -3,9 +3,9 @@
 import { useMemo, useState } from 'react'
 import { Check, Plus } from 'lucide-react'
 import { usePostHog } from 'posthog-js/react'
-import { Chip } from '@/components/emcn'
-import { AgentSkillsIcon } from '@/components/icons'
+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'
 
@@ -15,16 +15,6 @@ interface IntegrationSkillsSectionProps {
   integrationType: string
 }
 
-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 SkillRowProps {
   skill: SuggestedSkill
   added: boolean
@@ -56,8 +46,8 @@ function SkillRow({ skill, added, pending, onAdd }: SkillRowProps) {
 /**
  * Curated, research-backed skills for an integration. Each row adds the skill
  * to the workspace via the same `useCreateSkill` mutation the Skills page uses;
- * a skill already present in the workspace (matched by name) renders as
- * "Added" instead of an add button.
+ * `useSkills` is the single source of truth for the "Added" state, so a skill
+ * removed elsewhere correctly reverts to "Add".
  */
 export function IntegrationSkillsSection({
   skills,
@@ -67,27 +57,31 @@ export function IntegrationSkillsSection({
   const posthog = usePostHog()
   const { data: existingSkills = [] } = useSkills(workspaceId)
   const createSkill = useCreateSkill()
-  const [pendingName, setPendingName] = useState<string | null>(null)
-  const [optimisticAdded, setOptimisticAdded] = useState<ReadonlySet<string>>(new Set())
+  const [pendingNames, setPendingNames] = useState<ReadonlySet<string>>(new Set())
 
   const existingNames = useMemo(() => new Set(existingSkills.map((s) => s.name)), [existingSkills])
 
   const handleAdd = async (skill: SuggestedSkill, position: number) => {
-    setPendingName(skill.name)
+    // Track each in-flight add independently so concurrent adds keep their own
+    // "Adding..." state and cannot be double-submitted.
+    setPendingNames((prev) => new Set(prev).add(skill.name))
     try {
       await createSkill.mutateAsync({ workspaceId, skill })
-      // Mark added locally so the row flips to "Added" immediately — the list
-      // refetch that backs `existingNames` lands after this mutation resolves.
-      setOptimisticAdded((prev) => new Set(prev).add(skill.name))
       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 {
-      setPendingName(null)
+      setPendingNames((prev) => {
+        const next = new Set(prev)
+        next.delete(skill.name)
+        return next
+      })
     }
   }
 
@@ -100,8 +94,8 @@ export function IntegrationSkillsSection({
           <SkillRow
             key={skill.name}
             skill={skill}
-            added={existingNames.has(skill.name) || optimisticAdded.has(skill.name)}
-            pending={pendingName === skill.name}
+            added={existingNames.has(skill.name)}
+            pending={pendingNames.has(skill.name)}
             onAdd={() => handleAdd(skill, index)}
           />
         ))}

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