Organize Skills with Hats

This guide walks you through creating a hat, adding skills to it, and making it available to agents.

Prerequisites: At least one skill created in your workspace. If you have not done this yet, see Create Your First Skill.

Step 1: Navigate to Hats

Click Skills in the top navigation bar. This opens the skills and hats page for your workspace, showing any hats that already exist.

You can switch between three view modes using the toolbar:

• Grid View -- Card layout showing hat name, team, skill count, and color.
• List View -- Compact table rows for quick scanning.
• Hierarchy View -- Force-directed org chart showing the organizational structure with teams and hats as connected nodes.

Grouping and Sorting

Use the toolbar controls to organize the hats list:

• Group By: Organization (default, groups by team hierarchy), All Skills (skill-centric view), All Hats (flat list).
• Sort By: A-Z, Most Skills, Recently Edited.
• Search: Searches across hat names, team names, and skill names.

Step 2: Create a New Hat

Click the New Hat button at the top of the hats page. The hat creation dialog opens.

Step 3: Fill in the Hat Details

The creation form has the following fields:

• Name (required) -- A short name that reflects the role or use case. Good examples: Customer Support, Marketing, Data Analysis. Avoid vague names like General or Stuff.
• Description (optional) -- Explain what this hat is for and who should use it. Up to 500 characters.
• Instructions -- Rich text guidance for how the agent should behave when wearing this hat. Supports markdown formatting (bold, lists, code blocks, etc.).
• Color -- Pick a color to visually distinguish the hat: Red, Orange, Yellow, Green, Blue, Purple, Pink, or Gray.
• Team (required) -- Select an existing team or create a new one. Teams are part of an organizational hierarchy that you manage from the Organization Settings button (gear icon) on the Hats page. You can create nested teams (e.g., Engineering > Backend > API Team) up to 10 levels deep. Hats are assigned to leaf-level teams.
• Skills -- Select skills to include in this hat. If no skills exist yet, create them first and add them later.

Managing the Organization Hierarchy

Click the Organization Settings button (gear icon) on the Hats page to manage your team structure:

• Create new teams and nest them under existing ones.
• Rename, reorder, or delete teams.
• Build a hierarchy up to 10 levels deep to match your organization structure.

Step 4: Create the Hat

Click Create Hat. Skilder creates the hat and it appears in your hats list.

Step 5: Add Skills Later

If you did not add skills during creation, or want to add more:

1. Click a hat card to open its detail page.
2. Add or remove skills from the hat.
3. Save your changes.

Choose skills that belong together for the role this hat represents. For example, a "Marketing" hat might include:

• Social Media Posting
• Content Drafting
• Campaign Analytics

How Agents Access Hats

When an AI agent connects to Skilder using an API key, the following happens:

1. Skilder looks up the API key and resolves the workspace.
2. For each hat, Skilder gathers the included skills.
3. For each skill, Skilder gathers the associated tools.
4. The agent receives the full list of available tools, organized by skill and hat.

The agent can then discover and call any tool that belongs to its hats. If you add a new skill to a hat, agents gain access to the new skill on their next connection.

API Key → Workspace → Hats → Skills → Tools

This chain gives you layered control. You manage tools at the skill level, skills at the hat level, and hats at the workspace level.

Managing Hats Over Time

• Add skills later -- Open a hat and add new skills as you build them. Agents pick up the changes automatically.
• Remove skills -- Uncheck a skill from the hat to revoke access. Agents lose access on their next connection.
• Enable/disable a hat -- You can disable a hat to temporarily hide it from agents without deleting it or its skills. Disabled hats are grayed out in the UI. Re-enable at any time to restore access.
• Delete a hat -- Remove a hat entirely when it is no longer needed. This does not delete the skills themselves — they remain available for other hats.
• Reorganize with teams -- Move hats between teams to keep your organization structure clean as it grows.

Troubleshooting

• Agent cannot find expected tools -- Verify that the hat is enabled and includes the skill containing those tools. Check that the skill's MCP server is running.
• Skills missing from hat picker -- Make sure the skills are created in the same workspace. Skills from other workspaces do not appear.
• Changes not reflected in agent -- Reconnect the agent or restart the client. Some MCP clients cache the tool list on startup.

Next Steps

• Skills -- Create more skills to add to your hats.
• Tools -- Install additional MCP servers to expand the tools available to your skills.