Organize Skills with Roles

This guide walks you through creating a role, 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 Roles

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

You can switch between three view modes using the toolbar:

• Grid View -- Card layout showing role 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 roles as connected nodes.

Grouping and Sorting

Use the toolbar controls to organize the roles list:

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

Step 2: Create a New Role

Click the New Role button at the top of the roles page. The role creation dialog opens.

Step 3: Fill in the Role 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 role is for and who should use it. Up to 500 characters.
• Instructions -- Rich text guidance for how the agent should behave when wearing this role. Supports markdown formatting (bold, lists, code blocks, etc.).
• Color -- Pick a color to visually distinguish the role: 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 Roles page. You can create nested teams (e.g., Engineering > Backend > API Team) up to 10 levels deep. Roles are assigned to leaf-level teams.
• Skills -- Select skills to include in this role. 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 Roles 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 Role

Click Create Role. Skilder creates the role and it appears in your roles list.

Step 5: Add Skills Later

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

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

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

• Social Media Posting
• Content Drafting
• Campaign Analytics

How Agents Access Roles

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 role, 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 role.

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

API Key → Workspace → Roles → Skills → Tools

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

Managing Roles Over Time

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

Troubleshooting

• Agent cannot find expected tools -- Verify that the role is enabled and includes the skill containing those tools. Check that the skill's MCP server is running.
• Skills missing from role 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 roles.
• Tools -- Install additional MCP servers to expand the tools available to your skills.