improvement(ui): improved skills UI, validation, and permissions

Author: waleedlatif1

apps/docs/content/docs/en/skills/index.mdx

@@ -18,7 +18,9 @@ This means you can attach many skills to an agent without bloating its context w
 
 ## Creating Skills
 
-Go to **Settings** (gear icon) and select **Skills** under the Tools section.
+Go to **Settings** and select **Skills** under the Tools section.
+
+![Manage Skills](/static/skills/manage-skills.png)
 
 Click **Add** to create a new skill with three fields:
 
@@ -52,11 +54,22 @@ Use when the user asks you to write, optimize, or debug SQL queries.
 ...
 ```
 
+**Recommended structure:**
+- **When to use** — Specific triggers and scenarios
+- **Instructions** — Step-by-step guidance with numbered lists
+- **Examples** — Input/output samples showing expected behavior
+- **Common Patterns** — Reusable approaches for frequent tasks
+- **Edge Cases** — Gotchas and special considerations
+
+Keep skills focused and under 500 lines. If a skill grows too large, split it into multiple specialized skills.
+
 ## Adding Skills to an Agent
 
 Open any **Agent** block and find the **Skills** dropdown below the tools section. Select the skills you want the agent to have access to.
 
-Selected skills appear as chips that you can click to edit or remove.
+![Add Skill](/static/skills/add-skill.png)
+
+Selected skills appear as cards that you can click to edit or remove.
 
 ### What Happens at Runtime
 
@@ -69,12 +82,50 @@ When the workflow runs:
 
 This works across all supported LLM providers — the `load_skill` tool uses standard tool-calling, so no provider-specific configuration is needed.
 
-## Tips
+## Common Use Cases
+
+Skills are most valuable when agents need specialized knowledge or multi-step workflows:
+
+**Domain Expertise**
+- `api-integration-expert` — Best practices for calling specific APIs (authentication, rate limiting, error handling)
+- `data-transformation` — ETL patterns, data cleaning, and validation rules
+- `code-reviewer` — Code review guidelines specific to your team's standards
+
+**Workflow Templates**
+- `bug-investigation` — Step-by-step debugging methodology (reproduce → isolate → test → fix)
+- `feature-implementation` — Development workflow from requirements to deployment
+- `document-generator` — Templates and formatting rules for technical documentation
+
+**Company-Specific Knowledge**
+- `our-architecture` — System architecture diagrams, service dependencies, and deployment processes
+- `style-guide` — Brand guidelines, writing tone, UI/UX patterns
+- `customer-onboarding` — Standard procedures and common customer questions
+
+**When to use skills vs. agent instructions:**
+- Use **skills** for knowledge that applies across multiple workflows or changes frequently
+- Use **agent instructions** for task-specific context that's unique to a single agent
+
+## Best Practices
+
+**Writing Effective Descriptions**
+- **Be specific and keyword-rich** — Instead of "Helps with SQL", write "Write optimized SQL queries for PostgreSQL, MySQL, and SQLite, including index recommendations and query plan analysis"
+- **Include activation triggers** — Mention specific words or phrases that should prompt the skill (e.g., "Use when the user mentions PDFs, forms, or document extraction")
+- **Keep it under 200 words** — Agents scan descriptions quickly; make every word count
 
-- **Keep descriptions actionable** — Instead of "Helps with SQL", write "Write optimized SQL queries for PostgreSQL, MySQL, and SQLite, including index recommendations and query plan analysis"
+**Skill Scope and Organization**
 - **One skill per domain** — A focused `sql-expert` skill works better than a broad `database-everything` skill
-- **Use markdown structure** — Headers, lists, and code blocks help the agent parse and follow instructions
-- **Test iteratively** — Run your workflow and check if the agent activates the skill when expected
+- **Limit to 5-10 skills per agent** — More skills = more decision overhead; start small and add as needed
+- **Split large skills** — If a skill exceeds 500 lines, break it into focused sub-skills
+
+**Content Structure**
+- **Use markdown formatting** — Headers, lists, and code blocks help agents parse and follow instructions
+- **Provide examples** — Show input/output pairs so agents understand expected behavior
+- **Be explicit about edge cases** — Don't assume agents will infer special handling
+
+**Testing and Iteration**
+- **Test activation** — Run your workflow and verify the agent loads the skill when expected
+- **Check for false positives** — Make sure skills aren't activating when they shouldn't
+- **Refine descriptions** — If a skill isn't loading when needed, add more keywords to the description
 
 ## Learn More
 

apps/docs/public/static/skills/add-skill.png

@@ -130,39 +130,52 @@ export function SkillInput({
           onOpenChange={setOpen}
         />
 
-        {selectedSkills.length > 0 && (
-          <div className='flex flex-wrap gap-[4px]'>
-            {selectedSkills.map((stored) => {
-              const fullSkill = workspaceSkills.find((s) => s.id === stored.skillId)
-              return (
+        {selectedSkills.length > 0 &&
+          selectedSkills.map((stored) => {
+            const fullSkill = workspaceSkills.find((s) => s.id === stored.skillId)
+            return (
+              <div
+                key={stored.skillId}
+                className='group relative flex flex-col overflow-hidden rounded-[4px] border border-[var(--border-1)] transition-all duration-200 ease-in-out'
+              >
                 <div
-                  key={stored.skillId}
-                  className='flex cursor-pointer items-center gap-[4px] rounded-[4px] border border-[var(--border-1)] bg-[var(--surface-5)] px-[6px] py-[2px] font-medium text-[12px] text-[var(--text-secondary)] hover:bg-[var(--surface-6)]'
+                  className='flex cursor-pointer items-center justify-between gap-[8px] rounded-t-[4px] bg-[var(--surface-4)] px-[8px] py-[6.5px]'
                   onClick={() => {
                     if (fullSkill && !disabled && !isPreview) {
                       setEditingSkill(fullSkill)
                     }
                   }}
                 >
-                  <AgentSkillsIcon className='h-[10px] w-[10px] text-[var(--text-tertiary)]' />
-                  <span className='max-w-[140px] truncate'>{resolveSkillName(stored)}</span>
-                  {!disabled && !isPreview && (
-                    <button
-                      type='button'
-                      onClick={(e) => {
-                        e.stopPropagation()
-                        handleRemove(stored.skillId)
-                      }}
-                      className='ml-[2px] rounded-[2px] p-[1px] text-[var(--text-tertiary)] hover:bg-[var(--surface-7)] hover:text-[var(--text-secondary)]'
+                  <div className='flex min-w-0 flex-1 items-center gap-[8px]'>
+                    <div
+                      className='flex h-[16px] w-[16px] flex-shrink-0 items-center justify-center rounded-[4px]'
+                      style={{ backgroundColor: '#e0e0e0' }}
                     >
-                      <XIcon className='h-[10px] w-[10px]' />
-                    </button>
-                  )}
+                      <AgentSkillsIcon className='h-[10px] w-[10px] text-[#333]' />
+                    </div>
+                    <span className='truncate font-medium text-[13px] text-[var(--text-primary)]'>
+                      {resolveSkillName(stored)}
+                    </span>
+                  </div>
+                  <div className='flex flex-shrink-0 items-center gap-[8px]'>
+                    {!disabled && !isPreview && (
+                      <button
+                        type='button'
+                        onClick={(e) => {
+                          e.stopPropagation()
+                          handleRemove(stored.skillId)
+                        }}
+                        className='flex items-center justify-center text-[var(--text-tertiary)] transition-colors hover:text-[var(--text-primary)]'
+                        aria-label='Remove skill'
+                      >
+                        <XIcon className='h-[13px] w-[13px]' />
+                      </button>
+                    )}
+                  </div>
                 </div>
-              )
-            })}
-          </div>
-        )}
+              </div>
+            )
+          })}
       </div>
 
       <SkillModal

apps/docs/public/static/skills/manage-skills.png

@@ -6,6 +6,7 @@ import {
   isSubBlockVisibleForMode,
 } from '@/lib/workflows/subblocks/visibility'
 import type { BlockConfig, SubBlockConfig, SubBlockType } from '@/blocks/types'
+import { usePermissionConfig } from '@/hooks/use-permission-config'
 import { useWorkflowDiffStore } from '@/stores/workflow-diff'
 import { mergeSubblockState } from '@/stores/workflows/utils'
 import { useWorkflowStore } from '@/stores/workflows/workflow/store'
@@ -35,6 +36,7 @@ export function useEditorSubblockLayout(
   const blockDataFromStore = useWorkflowStore(
     useCallback((state) => state.blocks?.[blockId]?.data, [blockId])
   )
+  const { config: permissionConfig } = usePermissionConfig()
 
   return useMemo(() => {
     // Guard against missing config or block selection
@@ -100,6 +102,9 @@ export function useEditorSubblockLayout(
     const visibleSubBlocks = (config.subBlocks || []).filter((block) => {
       if (block.hidden) return false
 
+      // Hide skill-input subblock when skills are disabled via permissions
+      if (block.type === 'skill-input' && permissionConfig.disableSkills) return false
+
       // Check required feature if specified - declarative feature gating
       if (!isSubBlockFeatureEnabled(block)) return false
 
@@ -149,5 +154,6 @@ export function useEditorSubblockLayout(
     activeWorkflowId,
     isSnapshotView,
     blockDataFromStore,
+    permissionConfig.disableSkills,
   ])
 }

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/skill-input/skill-input.tsx

@@ -40,6 +40,7 @@ import { useCustomTools } from '@/hooks/queries/custom-tools'
 import { useMcpServers, useMcpToolsQuery } from '@/hooks/queries/mcp'
 import { useCredentialName } from '@/hooks/queries/oauth-credentials'
 import { useReactivateSchedule, useScheduleInfo } from '@/hooks/queries/schedules'
+import { useSkills } from '@/hooks/queries/skills'
 import { useDeployChildWorkflow } from '@/hooks/queries/workflows'
 import { useSelectorDisplayName } from '@/hooks/use-selector-display-name'
 import { useVariablesStore } from '@/stores/panel'
@@ -618,6 +619,43 @@ const SubBlockRow = memo(function SubBlockRow({
     return `${toolNames[0]}, ${toolNames[1]} +${toolNames.length - 2}`
   }, [subBlock?.type, rawValue, customTools, workspaceId])
 
+  /**
+   * Hydrates skill references to display names.
+   * Resolves skill IDs to their current names from the skills query.
+   */
+  const { data: workspaceSkills = [] } = useSkills(workspaceId || '')
+
+  const skillsDisplayValue = useMemo(() => {
+    if (subBlock?.type !== 'skill-input' || !Array.isArray(rawValue) || rawValue.length === 0) {
+      return null
+    }
+
+    const skillNames = rawValue
+      .map((skill: any) => {
+        if (!skill || typeof skill !== 'object') return null
+
+        // Priority 1: Resolve skill name from the skills query (fresh data)
+        if (skill.skillId) {
+          const foundSkill = workspaceSkills.find((s) => s.id === skill.skillId)
+          if (foundSkill?.name) return foundSkill.name
+        }
+
+        // Priority 2: Fall back to stored name (for deleted skills)
+        if (skill.name && typeof skill.name === 'string') return skill.name
+
+        // Priority 3: Use skillId as last resort
+        if (skill.skillId) return skill.skillId
+
+        return null
+      })
+      .filter((name): name is string => !!name)
+
+    if (skillNames.length === 0) return null
+    if (skillNames.length === 1) return skillNames[0]
+    if (skillNames.length === 2) return `${skillNames[0]}, ${skillNames[1]}`
+    return `${skillNames[0]}, ${skillNames[1]} +${skillNames.length - 2}`
+  }, [subBlock?.type, rawValue, workspaceSkills])
+
   const isPasswordField = subBlock?.password === true
   const maskedValue = isPasswordField && value && value !== '-' ? '•••' : null
 
@@ -627,6 +665,7 @@ const SubBlockRow = memo(function SubBlockRow({
     dropdownLabel ||
     variablesDisplayValue ||
     toolsDisplayValue ||
+    skillsDisplayValue ||
     knowledgeBaseDisplayName ||
     workflowSelectionName ||
     mcpServerDisplayName ||

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/hooks/use-editor-subblock-layout.ts

@@ -27,6 +27,13 @@ interface SkillModalProps {
 
 const KEBAB_CASE_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/
 
+interface FieldErrors {
+  name?: string
+  description?: string
+  content?: string
+  general?: string
+}
+
 export function SkillModal({
   open,
   onOpenChange,
@@ -43,7 +50,7 @@ export function SkillModal({
   const [name, setName] = useState('')
   const [description, setDescription] = useState('')
   const [content, setContent] = useState('')
-  const [formError, setFormError] = useState('')
+  const [errors, setErrors] = useState<FieldErrors>({})
   const [saving, setSaving] = useState(false)
 
   useEffect(() => {
@@ -57,7 +64,7 @@ export function SkillModal({
         setDescription('')
         setContent('')
       }
-      setFormError('')
+      setErrors({})
     }
   }, [open, initialValues])
 
@@ -71,24 +78,26 @@ export function SkillModal({
   }, [name, description, content, initialValues])
 
   const handleSave = async () => {
+    const newErrors: FieldErrors = {}
+
     if (!name.trim()) {
-      setFormError('Name is required')
-      return
-    }
-    if (name.length > 64) {
-      setFormError('Name must be 64 characters or less')
-      return
-    }
-    if (!KEBAB_CASE_REGEX.test(name)) {
-      setFormError('Name must be kebab-case (e.g. my-skill)')
-      return
+      newErrors.name = 'Name is required'
+    } else if (name.length > 64) {
+      newErrors.name = 'Name must be 64 characters or less'
+    } else if (!KEBAB_CASE_REGEX.test(name)) {
+      newErrors.name = 'Name must be kebab-case (e.g. my-skill)'
     }
+
     if (!description.trim()) {
-      setFormError('Description is required')
-      return
+      newErrors.description = 'Description is required'
     }
+
     if (!content.trim()) {
-      setFormError('Content is required')
+      newErrors.content = 'Content is required'
+    }
+
+    if (Object.keys(newErrors).length > 0) {
+      setErrors(newErrors)
       return
     }
 
@@ -113,7 +122,7 @@ export function SkillModal({
         error instanceof Error && error.message.includes('already exists')
           ? error.message
           : 'Failed to save skill. Please try again.'
-      setFormError(message)
+      setErrors({ general: message })
     } finally {
       setSaving(false)
     }
@@ -135,12 +144,16 @@ export function SkillModal({
                 value={name}
                 onChange={(e) => {
                   setName(e.target.value)
-                  if (formError) setFormError('')
+                  if (errors.name) setErrors((prev) => ({ ...prev, name: undefined }))
                 }}
               />
-              <span className='text-[11px] text-[var(--text-muted)]'>
-                Lowercase letters, numbers, and hyphens (e.g. my-skill)
-              </span>
+              {errors.name ? (
+                <p className='text-[12px] text-[var(--text-error)]'>{errors.name}</p>
+              ) : (
+                <span className='text-[11px] text-[var(--text-muted)]'>
+                  Lowercase letters, numbers, and hyphens (e.g. my-skill)
+                </span>
+              )}
             </div>
 
             <div className='flex flex-col gap-[4px]'>
@@ -153,10 +166,13 @@ export function SkillModal({
                 value={description}
                 onChange={(e) => {
                   setDescription(e.target.value)
-                  if (formError) setFormError('')
+                  if (errors.description) setErrors((prev) => ({ ...prev, description: undefined }))
                 }}
                 maxLength={1024}
               />
+              {errors.description && (
+                <p className='text-[12px] text-[var(--text-error)]'>{errors.description}</p>
+              )}
             </div>
 
             <div className='flex flex-col gap-[4px]'>
@@ -169,13 +185,18 @@ export function SkillModal({
                 value={content}
                 onChange={(e: ChangeEvent<HTMLTextAreaElement>) => {
                   setContent(e.target.value)
-                  if (formError) setFormError('')
+                  if (errors.content) setErrors((prev) => ({ ...prev, content: undefined }))
                 }}
                 className='min-h-[200px] resize-y font-mono text-[13px]'
               />
+              {errors.content && (
+                <p className='text-[12px] text-[var(--text-error)]'>{errors.content}</p>
+              )}
             </div>
 
-            {formError && <span className='text-[11px] text-[var(--text-error)]'>{formError}</span>}
+            {errors.general && (
+              <p className='text-[12px] text-[var(--text-error)]'>{errors.general}</p>
+            )}
           </div>
         </ModalBody>
         <ModalFooter className='items-center justify-between'>