refactor: rename requiredSkills to skills for semantic clarity (#673)

Rename `requiredSkills` to `skills` across all tool definitions to
better reflect the relationship: tools *belong* to skill categories
rather than *requiring* them. This makes the authorization model clearer
- a tool is enabled when ANY of its associated skills are granted.

Also rename `hasRequiredSkills` to `isEnabledBySkills` for consistency.

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: dcramer

packages/mcp-core/scripts/generate-definitions.ts

@@ -131,15 +131,12 @@ async function generateSkillDefinitions() {
       const t = tool as {
         name: string;
         description: string;
-        requiredSkills: string[];
+        skills: string[];
         requiredScopes: string[];
       };
 
       // Check if this tool is enabled by this skill
-      if (
-        Array.isArray(t.requiredSkills) &&
-        t.requiredSkills.includes(skill.id)
-      ) {
+      if (Array.isArray(t.skills) && t.skills.includes(skill.id)) {
         skillTools.push({
           name: t.name,
           description: t.description,

packages/mcp-core/scripts/validate-skills-mapping.ts

@@ -36,7 +36,7 @@ function getToolsForSkill(skill: Skill): string[] {
   const enabledTools: string[] = [];
 
   for (const [toolName, tool] of Object.entries(tools)) {
-    if (tool.requiredSkills.includes(skill)) {
+    if (tool.skills.includes(skill)) {
       enabledTools.push(toolName);
     }
   }
@@ -88,8 +88,8 @@ function findOrphanedTools(): string[] {
       continue;
     }
 
-    // Check if tool has no required skills (orphaned)
-    if (tool.requiredSkills.length === 0) {
+    // Check if tool has no skills (orphaned)
+    if (tool.skills.length === 0) {
       orphanedTools.push(toolName);
     }
   }

packages/mcp-core/src/server.ts

@@ -37,7 +37,7 @@ import { logIssue, type LogIssueOptions } from "./telem/logging";
 import { formatErrorForUser } from "./internal/error-handling";
 import { LIB_VERSION } from "./version";
 import { MCP_SERVER_NAME } from "./constants";
-import { hasRequiredSkills, type Skill } from "./skills";
+import { isEnabledBySkills, type Skill } from "./skills";
 import {
   getConstraintParametersToInject,
   getConstraintKeysToFilter,
@@ -155,21 +155,21 @@ function configureServer({
      * ==========================
      *
      * Tools are filtered at registration time based on grantedSkills.
-     * Tool must have non-empty `requiredSkills` array to be exposed.
-     * Empty `requiredSkills: []` means intentionally excluded from skills system.
+     * Tool must have non-empty `skills` array to be exposed.
+     * Empty `skills: []` means intentionally excluded from skills system.
      *
      * In agent mode, authorization is skipped - use_sentry handles it internally.
      *
      * ## Examples:
      *    ```typescript
-     *    // Tool available in "triage" skill only:
-     *    { requiredSkills: ["triage"] }
+     *    // Tool belongs to "triage" skill only:
+     *    { skills: ["triage"] }
      *
-     *    // Tool available to ALL skills (foundational tool like whoami):
-     *    { requiredSkills: ALL_SKILLS }
+     *    // Tool belongs to ALL skills (foundational tool like whoami):
+     *    { skills: ALL_SKILLS }
      *
      *    // Tool excluded from skills system (like use_sentry in agent mode):
-     *    { requiredSkills: [] }
+     *    { skills: [] }
      *    ```
      */
     let allowed = false;
@@ -178,12 +178,12 @@ function configureServer({
     if (agentMode) {
       allowed = true;
     }
-    // Skills system: tool must have non-empty requiredSkills to be exposed
+    // Skills system: tool must have non-empty skills to be exposed
     else if (grantedSkills) {
-      if (tool.requiredSkills && tool.requiredSkills.length > 0) {
-        allowed = hasRequiredSkills(grantedSkills, tool.requiredSkills);
+      if (tool.skills && tool.skills.length > 0) {
+        allowed = isEnabledBySkills(grantedSkills, tool.skills);
       }
-      // Empty requiredSkills means NOT exposed via skills system
+      // Empty skills means NOT exposed via skills system
     }
 
     // Skip tool if not allowed by active authorization system

packages/mcp-core/src/skills.test.ts

@@ -4,7 +4,7 @@ import {
   DEFAULT_SKILLS,
   isValidSkill,
   parseSkills,
-  hasRequiredSkills,
+  isEnabledBySkills,
   type Skill,
 } from "./skills";
 
@@ -113,31 +113,31 @@ describe("skills module", () => {
     });
   });
 
-  describe("hasRequiredSkills", () => {
-    it("returns true when any required skill is granted", () => {
+  describe("isEnabledBySkills", () => {
+    it("returns true when any tool skill is granted", () => {
       const grantedSkills = new Set<Skill>(["inspect", "docs"]);
-      expect(hasRequiredSkills(grantedSkills, ["inspect"])).toBe(true);
-      expect(hasRequiredSkills(grantedSkills, ["docs"])).toBe(true);
-      expect(hasRequiredSkills(grantedSkills, ["inspect", "triage"])).toBe(
+      expect(isEnabledBySkills(grantedSkills, ["inspect"])).toBe(true);
+      expect(isEnabledBySkills(grantedSkills, ["docs"])).toBe(true);
+      expect(isEnabledBySkills(grantedSkills, ["inspect", "triage"])).toBe(
         true,
       );
     });
 
-    it("returns false when no required skills are granted", () => {
+    it("returns false when no tool skills are granted", () => {
       const grantedSkills = new Set<Skill>(["inspect", "docs"]);
-      expect(hasRequiredSkills(grantedSkills, ["triage"])).toBe(false);
+      expect(isEnabledBySkills(grantedSkills, ["triage"])).toBe(false);
       expect(
-        hasRequiredSkills(grantedSkills, ["triage", "project-management"]),
+        isEnabledBySkills(grantedSkills, ["triage", "project-management"]),
       ).toBe(false);
     });
 
     it("returns false when grantedSkills is undefined", () => {
-      expect(hasRequiredSkills(undefined, ["inspect"])).toBe(false);
+      expect(isEnabledBySkills(undefined, ["inspect"])).toBe(false);
     });
 
-    it("returns false when requiredSkills is empty", () => {
+    it("returns false when toolSkills is empty", () => {
       const grantedSkills = new Set<Skill>(["inspect"]);
-      expect(hasRequiredSkills(grantedSkills, [])).toBe(false);
+      expect(isEnabledBySkills(grantedSkills, [])).toBe(false);
     });
   });
 });

packages/mcp-core/src/skills.ts

@@ -82,8 +82,8 @@ export async function getSkillsArrayWithCounts(): Promise<SkillDefinition[]> {
 
   // Count tools for each skill
   for (const tool of Object.values(tools)) {
-    if (Array.isArray(tool.requiredSkills)) {
-      for (const skill of tool.requiredSkills) {
+    if (Array.isArray(tool.skills)) {
+      for (const skill of tool.skills) {
         counts.set(skill as Skill, (counts.get(skill as Skill) || 0) + 1);
       }
     }
@@ -108,13 +108,13 @@ export function isValidSkill(skill: string): skill is Skill {
   return skill in SKILLS;
 }
 
-// Check if tool is enabled by skills
-export function hasRequiredSkills(
+// Check if tool is enabled by granted skills (ANY match = enabled)
+export function isEnabledBySkills(
   grantedSkills: Set<Skill> | undefined,
-  requiredSkills: Skill[],
+  toolSkills: Skill[],
 ): boolean {
-  if (!grantedSkills || requiredSkills.length === 0) return false;
-  return requiredSkills.some((skill) => grantedSkills.has(skill));
+  if (!grantedSkills || toolSkills.length === 0) return false;
+  return toolSkills.some((skill) => grantedSkills.has(skill));
 }
 
 // Parse and validate skills from input
@@ -160,10 +160,8 @@ export async function getScopesForSkills(
 
   // Iterate through all tools and collect required scopes for tools enabled by granted skills
   for (const tool of Object.values(tools)) {
-    // Check if any of the tool's required skills are granted
-    const toolEnabled = tool.requiredSkills.some((reqSkill) =>
-      grantedSkills.has(reqSkill),
-    );
+    // Check if any of the tool's skills are granted
+    const toolEnabled = tool.skills.some((skill) => grantedSkills.has(skill));
 
     // If tool is enabled by granted skills, add its required scopes
     if (toolEnabled) {

packages/mcp-core/src/tools/analyze-issue-with-seer.ts

@@ -25,7 +25,7 @@ import {
 
 export default defineTool({
   name: "analyze_issue_with_seer",
-  requiredSkills: ["seer"], // Only available in seer skill
+  skills: ["seer"], // Only available in seer skill
   requiredScopes: [], // No Sentry API scopes required - authorization via 'seer' skill
   description: [
     "Use Seer to analyze production errors and get detailed root cause analysis with specific code fixes.",

packages/mcp-core/src/tools/create-dsn.ts

@@ -11,7 +11,7 @@ import {
 
 export default defineTool({
   name: "create_dsn",
-  requiredSkills: ["project-management"], // Only available in project-management skill
+  skills: ["project-management"], // Only available in project-management skill
   requiredScopes: ["project:write"],
   description: [
     "Create an additional DSN for an EXISTING project.",

packages/mcp-core/src/tools/create-project.ts

@@ -14,7 +14,7 @@ import {
 
 export default defineTool({
   name: "create_project",
-  requiredSkills: ["project-management"], // Only available in project-management skill
+  skills: ["project-management"], // Only available in project-management skill
   requiredScopes: ["project:write", "team:read"],
   description: [
     "Create a new project in Sentry (includes DSN automatically).",

packages/mcp-core/src/tools/create-team.ts

@@ -7,7 +7,7 @@ import { ParamOrganizationSlug, ParamRegionUrl } from "../schema";
 
 export default defineTool({
   name: "create_team",
-  requiredSkills: ["project-management"], // Only available in project-management skill
+  skills: ["project-management"], // Only available in project-management skill
   requiredScopes: ["team:write"],
   description: [
     "Create a new team in Sentry.",

packages/mcp-core/src/tools/find-dsns.ts

@@ -10,7 +10,7 @@ import {
 
 export default defineTool({
   name: "find_dsns",
-  requiredSkills: ["project-management"], // DSN management is part of project setup
+  skills: ["project-management"], // DSN management is part of project setup
   requiredScopes: ["project:read"],
   description: [
     "List all Sentry DSNs for a specific project.",