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

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

* stronger typing for Skill interface

* added missing docs description

* ack comment

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
 
-- **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"
+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
+
+**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/content/docs/en/tools/airweave.mdx

@@ -10,6 +10,21 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
   color="#6366F1"
 />
 
+{/* MANUAL-CONTENT-START:intro */}
+[Airweave](https://airweave.ai/) is an AI-powered semantic search platform that helps you discover and retrieve knowledge across all your synced data sources. Built for modern teams, Airweave enables fast, relevant search results using neural, hybrid, or keyword-based strategies tailored to your needs.
+
+With Airweave, you can:
+
+- **Search smarter**: Use natural language queries to uncover information stored across your connected tools and databases
+- **Unify your data**: Seamlessly access content from sources like code, docs, chat, emails, cloud files, and more
+- **Customize retrieval**: Select between hybrid (semantic + keyword), neural, or keyword search strategies for optimal results
+- **Boost recall**: Expand search queries with AI to find more comprehensive answers
+- **Rerank results using AI**: Prioritize the most relevant answers with powerful language models
+- **Get instant answers**: Generate clear, AI-powered responses synthesized from your data
+
+In Sim, the Airweave integration empowers your agents to search, summarize, and extract insights from all your organization’s data via a single tool. Use Airweave to drive rich, contextual knowledge retrieval within your workflows—whether answering questions, generating summaries, or supporting dynamic decision-making.
+{/* MANUAL-CONTENT-END */}
+
 ## Usage Instructions
 
 Search across your synced data sources using Airweave. Supports semantic search with hybrid, neural, or keyword retrieval strategies. Optionally generate AI-powered answers from search results.