> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill Exchange Actions

> Integrate Skill Exchange with the Backstage Actions Registry to programmatically search skills, find experts, and automate workflows.

`@spotify/backstage-plugin-skill-exchange-backend-module-actions`

The Skill Exchange Actions module integrates with Backstage's [Actions Registry](https://backstage.io/docs/backend-system/core-services/actions-registry/), enabling programmatic discovery of skills and experts within your organization. These actions are ideal for integration with AI assistants, automation workflows, and custom backend plugins.

### Installation

To use these actions, install the actions module as described in [Setup & Installation](./setup-and-installation#optional-skill-exchange-actions).

```ts packages/backend/src/index.ts theme={"theme":{"light":"github-light","dark":"dracula"}}
backend.add(
  import('@spotify/backstage-plugin-skill-exchange-backend-module-actions'),
);
```

### Available Actions

Each action declares attributes that indicate its behavior:

* **`readOnly`**: The action only reads data and does not make modifications
* **`idempotent`**: Repeated calls with the same input produce the same result
* **`destructive`**: The action can delete or permanently modify data

| Action           | Attributes                                                 | Description                                         |
| ---------------- | ---------------------------------------------------------- | --------------------------------------------------- |
| `search-skills`  | `readOnly: true`, `idempotent: true`, `destructive: false` | Discover skills by name, category, or relationships |
| `search-experts` | `readOnly: true`, `idempotent: true`, `destructive: false` | Find experts based on skills or team membership     |

<Tip>
  Always check an action's attributes before using it in automated workflows to
  understand its potential side effects.
</Tip>

***

## search-skills Action

Discover skills in your organization by name, category, or relationships.

### Use Cases

* **Skill discovery**: Find skills that match specific criteria for team planning
* **Related technologies**: Discover skills related to ones your team already uses
* **Onboarding**: Help new team members explore available learning paths
* **Automation**: Power AI assistants and chatbots with skill discovery

### Parameters

| Parameter           | Type       | Required | Description                                                                                 |
| ------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------- |
| `query`             | `string`   | No       | Search term for skill name (partial matching)                                               |
| `category`          | `string`   | No       | Filter by category: `DISCIPLINE`, `FRAMEWORKS`, `INFRASTRUCTURE`, `LANGUAGES`, `TECHNIQUES` |
| `limit`             | `number`   | No       | Maximum results to return (1-100, default: 50)                                              |
| `relatedToSkillIds` | `number[]` | No       | Find skills related to these skill IDs                                                      |

### Output

| Key      | Type                                                    | Description                     |
| -------- | ------------------------------------------------------- | ------------------------------- |
| `skills` | `Array<{ id: number; name: string; category: string }>` | List of matching skills         |
| `total`  | `number`                                                | Total count of matching results |

***

## search-experts Action

Find experts in your organization based on skills or team membership.

### Use Cases

* **Expert discovery**: Find subject matter experts for specific technologies
* **Team formation**: Identify potential team members with required skills
* **Code review**: Find qualified reviewers for specific technology areas
* **Mentorship**: Connect mentees with mentors who have relevant expertise
* **Knowledge sharing**: Identify experts who can lead workshops or training

### Parameters

| Parameter    | Type       | Required | Description                                    |
| ------------ | ---------- | -------- | ---------------------------------------------- |
| `query`      | `string`   | No       | Search term for expert name or description     |
| `teams`      | `string[]` | No       | Filter by team membership                      |
| `skillNames` | `string[]` | No       | Filter by specific skill names                 |
| `limit`      | `number`   | No       | Maximum results to return (1-100, default: 20) |

### Output

| Key       | Type                                                                              | Description                     |
| --------- | --------------------------------------------------------------------------------- | ------------------------------- |
| `experts` | `Array<{ displayName: string; name: string; skills: string[]; teams: string[] }>` | List of matching experts        |
| `total`   | `number`                                                                          | Total count of matching results |

***

## Programmatic Usage in Backend Plugins

You can use these actions programmatically in your own backend plugins by accessing the Actions Registry Service:

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
import {
  createBackendPlugin,
  coreServices,
} from '@backstage/backend-plugin-api';
import { actionsRegistryServiceRef } from '@backstage/backend-plugin-api/alpha';

export const myPlugin = createBackendPlugin({
  pluginId: 'my-plugin',
  register(env) {
    env.registerInit({
      deps: {
        actionsRegistry: actionsRegistryServiceRef,
        logger: coreServices.logger,
      },
      async init({ actionsRegistry, logger }) {
        // Get reference to skill exchange actions
        const searchSkillsAction = actionsRegistry.get('search-skills');
        const searchExpertsAction = actionsRegistry.get('search-experts');

        // Use the actions in your logic
        const skillsResult = await searchSkillsAction?.action({
          input: {
            query: 'React',
            category: 'FRAMEWORKS',
            limit: 20,
          },
          logger,
          credentials: {
            /* your credentials */
          },
        });

        logger.info(`Found ${skillsResult?.output.total} skills`);
      },
    });
  },
});
```

## Integration with AI Assistants

These actions work seamlessly with AI assistants and automation tools. When integrating actions into AI-powered workflows, check each action's attributes to understand its behavior:

* Actions with `readOnly: true` can be called safely without modifying data
* Actions with `idempotent: true` can be retried safely on failure
* Actions with `destructive: true` should require explicit user confirmation before execution