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

# Skills, plugins, agents, instructions, and extensions

> Use ServerRpc in Laravel Copilot SDK to manage skills, plugins, agents, instructions, extensions, and LSP settings.

## Skills, plugins, agents, instructions, and extensions

Scope: ServerRpc (server-wide operations tied to the Client)

For an overview of RPC and the list of all RPC pages, see [RPC](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md).

```php theme={null}
use Revolution\Copilot\Enums\CatalogCandidateKind;
use Revolution\Copilot\Enums\CatalogCapability;
use Revolution\Copilot\Enums\CatalogSelectionDecision;
use Revolution\Copilot\Enums\CatalogTrustTier;
use Revolution\Copilot\Enums\SkillInstallationManagementOutcomeKind;
use Revolution\Copilot\Enums\SkillInstallationManagementResultKind;
use Revolution\Copilot\Enums\SkillsRemoveSourceOutcomeKind;
use Revolution\Copilot\Types\Rpc\AgentsDiscoverRequest;
use Revolution\Copilot\Types\Rpc\AgentsGetDiscoveryPathsRequest;
use Revolution\Copilot\Types\Rpc\CatalogClientContract;
use Revolution\Copilot\Types\Rpc\CatalogGetGeneratedFeedRequest;
use Revolution\Copilot\Types\Rpc\CatalogGetSavedFeedRequest;
use Revolution\Copilot\Types\Rpc\CatalogMaterializationReference;
use Revolution\Copilot\Types\Rpc\CatalogRecommendRequest;
use Revolution\Copilot\Types\Rpc\CatalogSearchRequest;
use Revolution\Copilot\Types\Rpc\CatalogSelectionRequest;
use Revolution\Copilot\Types\Rpc\InstructionsDiscoverRequest;
use Revolution\Copilot\Types\Rpc\InstructionsGetDiscoveryPathsRequest;
use Revolution\Copilot\Types\Rpc\PluginsBuiltinSetRequest;
use Revolution\Copilot\Types\Rpc\PluginsDisableRequest;
use Revolution\Copilot\Types\Rpc\PluginsEnableRequest;
use Revolution\Copilot\Types\Rpc\PluginsInstallRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesAddRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesBrowseRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesRefreshRequest;
use Revolution\Copilot\Types\Rpc\PluginsMarketplacesRemoveRequest;
use Revolution\Copilot\Types\Rpc\PluginsUninstallRequest;
use Revolution\Copilot\Types\Rpc\PluginsUpdateRequest;
use Revolution\Copilot\Types\Rpc\SkillApplyInstallRequest;
use Revolution\Copilot\Types\Rpc\SkillApplyUninstallRequest;
use Revolution\Copilot\Types\Rpc\SkillInstallationOperationRequest;
use Revolution\Copilot\Types\Rpc\SkillInstallationsRequest;
use Revolution\Copilot\Types\Rpc\SkillPlanInstallRequest;
use Revolution\Copilot\Types\Rpc\SkillPlanUninstallRequest;
use Revolution\Copilot\Types\Rpc\SkillSetEnabledRequest;
use Revolution\Copilot\Types\Rpc\SkillsInstallSourceRequest;
use Revolution\Copilot\Types\Rpc\SkillsRemoveSourceRequest;
use Revolution\Copilot\Types\Rpc\SkillsGetDiscoveryPathsRequest;

// skills (server-level skill management)
// Discover skills
$result = Copilot::client()->rpc()->skills()->discover();
// $result->skills is an array of ServerSkill
// Optionally specify project paths
$result = Copilot::client()->rpc()->skills()->discover(new SkillsDiscoverRequest(
    projectPaths: ['/path/to/project'],
    skillDirectories: ['/custom/skills'],
));

// Configure skills to disable
Copilot::client()->rpc()->skills()->config()->setDisabledSkills(
    new SkillsConfigSetDisabledSkillsRequest(disabledSkills: ['skill-name'])
);

// Enable or disable an individual skill
Copilot::client()->rpc()->skills()->config()->setSkillDisabled(
    new SkillsConfigSetSkillDisabledRequest(name: 'skill-name', disabled: true)
);

// Install directly from an HTTPS URL or a local file (experimental)
$skills = Copilot::client()->rpc()->skills();
$installed = $skills->installSource(new SkillsInstallSourceRequest(
    source: 'https://example.test/skills/review/SKILL.md',
    cwd: '/workspace',
    personalSkillsDir: '/home/user/.copilot/skills',
    projectSkillsDir: '/workspace/.copilot/skills',
    project: false,
    skillDirectories: ['/custom/skills'],
    userAgent: 'my-app/1.0',
));
// Persist the returned skillDirectories on the caller side
$skillDirectories = $installed->skillDirectories;

// Unregister a discovery directory. The directory contents aren't deleted
$removed = $skills->removeSource(new SkillsRemoveSourceRequest(
    target: '/custom/skills',
    cwd: '/workspace',
    skillDirectories: $skillDirectories,
));
if ($removed->kind === SkillsRemoveSourceOutcomeKind::Removed) {
    $skillDirectories = $removed->result->skillDirectories;
}
// If deleting files requires an inventory and you omit it, needs-inventory is returned and nothing changes

// Select a skill candidate with catalog.search → catalog.select (experimental)

$contract = new CatalogClientContract(1, ['catalog-selection', 'ai-skill-installation']);
$catalog = Copilot::client()->rpc()->catalog();

// Get official product recommendations from a product name and a complete task (experimental)
$recommendations = $catalog->recommend(new CatalogRecommendRequest(
    contract: new CatalogClientContract(1, [CatalogCapability::CatalogRecommend->value]),
    query: 'Review this repository and identify security issues.',
    product: 'GitHub Copilot',
));

$search = $catalog->search(new CatalogSearchRequest(
    contract: $contract,
    query: 'code review skill',
    kinds: [CatalogCandidateKind::AiSkill],
));
$selection = $catalog->select(new CatalogSelectionRequest(
    contract: $contract,
    sessionId: $sessionId,
    selectionRef: $search['candidates'][0]['selectionRef'],
    outcome: CatalogSelectionDecision::Selected,
));

// Category filters require catalog-search-categories
$categoryContract = new CatalogClientContract(3, [
    CatalogCapability::CatalogSearchCategories->value,
]);
$categorySearch = $catalog->search(new CatalogSearchRequest(
    contract: $categoryContract,
    query: 'design tools',
    categories: ['design', 'test'],
));
// When you specify policySessionId, also require credential-required and session-bound in the contract;
// it binds only to an existing attached session. It never creates or resumes a session.

// Saved and generated catalog feeds (credential required)
$feedContract = new CatalogClientContract(3, [
    CatalogCapability::CatalogFeeds->value,
    CatalogCapability::CatalogSearchCredentialRequired->value,
]);
$savedFeed = $catalog->getSavedFeed(new CatalogGetSavedFeedRequest(
    contract: $feedContract,
    feedId: 'opaque-feed-id',
    trustTiers: [CatalogTrustTier::T1],
));

// To bind to an existing attached session, also require the session-bound capability
$sessionFeedContract = new CatalogClientContract(3, [
    CatalogCapability::CatalogFeeds->value,
    CatalogCapability::CatalogSearchCredentialRequired->value,
    CatalogCapability::CatalogSearchSessionBound->value,
]);
$generatedFeed = $catalog->getGeneratedFeed(new CatalogGetGeneratedFeedRequest(
    contract: $sessionFeedContract,
    strategy: 'telemetry',
    key: 'popular',
    policySessionId: $sessionId,
    trustTiers: [CatalogTrustTier::T1, CatalogTrustTier::T2],
));
// entries preserve feed order. Entries that don't match the trust tier keep their position as filtered,
// and entries that can't be displayed are returned as unavailable with a reason.
// If the feed doesn't exist, you get kind=unavailable, reason=feed-not-found. Auth, negotiation, and policy denials
// are also returned as their own typed results, and catalog feed RPCs never install or configure anything.

// Plan and apply a skill installation

$skills = Copilot::client()->rpc()->skills();
if ($selection['kind'] === 'selected') {
    $planned = $skills->planInstall(new SkillPlanInstallRequest(
        contract: $contract,
        candidateHandle: $selection['candidateHandle'],
        policySessionId: $sessionId,
    ));
    if ($planned->kind === SkillInstallationManagementResultKind::Outcome
        && $planned->outcome?->kind === SkillInstallationManagementOutcomeKind::InstallPlanned) {
        // applyInstall() applies after confirmation via installations.confirm
        $result = $skills->applyInstall(new SkillApplyInstallRequest(
            contract: $contract,
            planHandle: $planned->outcome->plan['planHandle'],
            policySessionId: $sessionId,
        ));
    }
}

// Installed skills and in-progress operations
$installations = $skills->installations();
$owned = $installations->list(new SkillInstallationsRequest($contract, $sessionId));
$pending = $installations->recover(new SkillInstallationsRequest($contract, $sessionId));
$status = $installations->status(new SkillInstallationOperationRequest($contract, 'operation-id'));
$cancelled = $installations->cancel(new SkillInstallationOperationRequest($contract, 'operation-id'));
$enabled = $installations->setEnabled(new SkillSetEnabledRequest(
    contract: $contract,
    installationId: 'installation-id',
    enabled: true,
    policySessionId: $sessionId,
));

// Uninstalling also applies after reviewing the plan
$removalPlan = $skills->planUninstall(new SkillPlanUninstallRequest(
    contract: $contract,
    installationId: 'installation-id',
    policySessionId: $sessionId,
));
$removed = $skills->applyUninstall(new SkillApplyUninstallRequest(
    contract: $contract,
    planHandle: $removalPlan['planHandle'],
    policySessionId: $sessionId,
));

// skills: get directories where skills can be created (experimental)
// List of directories the runtime recognizes when you place skills in them

$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths();
// $result->paths is an array of SkillDiscoveryPath
// $result->paths[0]->path - Directory path
// $result->paths[0]->scope - Scope (user, project, plugin)
// $result->paths[0]->preferredForCreation - Whether it's the recommended directory for new creation
// Optionally narrow by scope
$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths(
    new SkillsGetDiscoveryPathsRequest(scope: 'project')
);

// plugins (server-scoped plugin management)

$plugins = Copilot::client()->rpc()->plugins();
$result = $plugins->list(); // Returns a PluginList
$installed = $plugins->install(new PluginsInstallRequest(source: 'eslint@official'));
$plugins->uninstall(new PluginsUninstallRequest(name: 'eslint@official'));
$plugins->update(new PluginsUpdateRequest(name: 'eslint@official'));
$plugins->updateAll();
$plugins->enable(new PluginsEnableRequest(names: ['eslint@official']));
$plugins->disable(new PluginsDisableRequest(names: ['eslint@official']));
// To distinguish direct installs with the same name, pass the directSourceId from list() in names
$plugins->enable(new PluginsEnableRequest(names: ['opaque-direct-source-id']));
$plugins->disable(new PluginsDisableRequest(names: ['opaque-direct-source-id']));

// Configure built-in plugin directories
$plugins->builtin()->set(new PluginsBuiltinSetRequest(paths: ['/opt/copilot/plugins']));

// If you specify directories used by all sessions in the client config,
// Client::start() registers them automatically before the first session is created
// config/copilot.php: 'builtin_plugin_directories' => ['/opt/copilot/plugins']

// Marketplace management
$marketplaces = $plugins->marketplaces();
$marketplaces->list();
$marketplaces->add(new PluginsMarketplacesAddRequest(source: 'github/copilot-plugins'));
$marketplaces->remove(new PluginsMarketplacesRemoveRequest(name: 'official', force: true));
$marketplaces->browse(new PluginsMarketplacesBrowseRequest(name: 'official'));
$marketplaces->refresh(new PluginsMarketplacesRefreshRequest(name: 'official'));

// agents (experimental: custom agent management)
// Discover custom agents

$result = Copilot::client()->rpc()->agents()->discover();
// $result->agents is an array of AgentInfo
$result = Copilot::client()->rpc()->agents()->discover(new AgentsDiscoverRequest(
    projectPaths: ['/path/to/project'],
    excludeHostAgents: true,
));

// Get directories where agents can be created (experimental)

$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths();
// $result->paths is an array of AgentDiscoveryPath
// $result->paths[0]->path - Directory path
// $result->paths[0]->scope - Scope (user, project, plugin)
// $result->paths[0]->preferredForCreation - Whether it's the recommended directory for new creation
$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths(
    new AgentsGetDiscoveryPathsRequest(scope: 'user')
);

// instructions (experimental: instruction management)
// Discover instructions

$result = Copilot::client()->rpc()->instructions()->discover();
// $result->sources is an array of InstructionSource
$result = Copilot::client()->rpc()->instructions()->discover(
    new InstructionsDiscoverRequest(projectPaths: ['/path/to/project'])
);

// Get files/directories where instructions can be created (experimental)

$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths();
// $result->paths is an array of InstructionDiscoveryPath
// $result->paths[0]->path - File/directory path
// $result->paths[0]->location - Location (user, repository, working-directory, plugin)
// $result->paths[0]->kind - Kind (file, directory)
// $result->paths[0]->preferredForCreation - Whether it's recommended for new creation
$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths(
    new InstructionsGetDiscoveryPathsRequest(location: 'repository')
);

// extensions (experimental: manage persisted extensions)
$result = Copilot::client()->rpc()->extensions()->discover();
Copilot::client()->rpc()->extensions()->enable(['ids' => ['user:demo']]);
Copilot::client()->rpc()->extensions()->disable(['ids' => ['plugin:demo']]);
```

## Agent Plugin catalog candidates

Require `agent-plugin-discovery` in `catalog.search` and specify `plugin` in the search `kinds` to get Agent Plugin candidates. To receive `application/vnd.anthropic.claude-plugin+json` and `application/agent-plugin+json` in addition to the standard format `application/vnd.github.copilot-plugin`, require `agent-plugin-formats` in addition to `agent-plugin-discovery`.

`agent-plugin-confirmed-installation` is a capability that returns installability and a plan for review. Require it together with `agent-plugin-discovery` as well. When granted, candidates include `installability`, whose value is one of `installable`, `install-data-unavailable`, `feature-disabled`, or `not-installable-kind`. `installPlan` is included only when `installability` is `installable`. The plan is data for review, and this catalog RPC never performs the installation.

The plan's `sources` contains `materialization`, `marketplace`, and `repository` candidates in priority order. A marketplace records its name and repository, and a direct repository records the repository and an optional path. In a materialization-only plan, `pluginName` is omitted and `components` is empty. Check the name and what will actually be installed in the review returned by `plugins.planInstall()`.

For a selected candidate, `plugins.planInstall()` creates a validated plan with no side effects. `plugins.applyInstall()` asks the user for explicit confirmation and applies the plan if allowed. The plugin is registered in a disabled state after it's applied.

The review's `mcpServers` shows the server names, transport, and, for remote servers, the host declared by the validated files. This isn't a safety guarantee, so have the user review the contents before giving explicit confirmation. An installed plugin's `description` comes from the manifest. `verifiedSource` shows the GitHub repository and pinned commit, and exists only for direct installs pinned to a commit. `iconUrl` is external, untrusted content, so don't send credentials or GitHub credentials when fetching it. Credentials themselves are never returned as refusal reasons.

For a `network-failure` installation result, you can check the `CatalogNetworkFailureReason`, the HTTP `statusCode`, an optional `retryAfterSeconds`, and a `message` that's safe to display.

```php theme={null}
use Revolution\Copilot\Enums\CatalogReferenceInstallationResultKind;
use Revolution\Copilot\Enums\PluginInstallationManagementOutcomeKind;
use Revolution\Copilot\Types\Rpc\CatalogClientContract;
use Revolution\Copilot\Types\Rpc\PluginApplyInstallRequest;
use Revolution\Copilot\Types\Rpc\PluginPlanInstallRequest;

$contract = new CatalogClientContract(3, [
    'agent-plugin-confirmed-installation',
]);
$plugins = Copilot::client()->rpc()->plugins();

$planned = $plugins->planInstall(new PluginPlanInstallRequest(
    candidateHandle: $candidateHandle,
    contract: $contract,
    policySessionId: $sessionId,
));

if ($planned->kind === CatalogReferenceInstallationResultKind::Outcome
    && $planned->outcome?->kind === PluginInstallationManagementOutcomeKind::InstallPlanned) {
    $applied = $plugins->applyInstall(new PluginApplyInstallRequest(
        contract: $contract,
        planHandle: $planned->outcome->plan->planHandle,
        policySessionId: $sessionId,
    ));
}
```

To plan from an Agent Finder materialisation reference, use `catalog.planInstallFromReference()`. The result's `outcome->kind` is one of `plugin-install-planned`, `skill-install-planned`, or `refused`. Pass plugin plans to `plugins.applyInstall()` and skill plans to `skills.applyInstall()`.

```php theme={null}
use Revolution\Copilot\Enums\CatalogCapability;
use Revolution\Copilot\Enums\CatalogReferenceInstallationOutcomeKind;
use Revolution\Copilot\Enums\CatalogReferenceInstallationResultKind;
use Revolution\Copilot\Types\Rpc\CatalogClientContract;
use Revolution\Copilot\Types\Rpc\CatalogMaterializationReference;
use Revolution\Copilot\Types\Rpc\CatalogPlanInstallFromReferenceRequest;
use Revolution\Copilot\Types\Rpc\PluginApplyInstallRequest;
use Revolution\Copilot\Types\Rpc\SkillApplyInstallRequest;

$referenceContract = new CatalogClientContract(3, [
    CatalogCapability::CatalogReferenceInstallation->value,
    CatalogCapability::AgentPluginConfirmedInstallation->value,
    CatalogCapability::SkillConfirmedInstallation->value,
]);
$reference = new CatalogMaterializationReference(
    resourceId: '12345',
    revisionId: '67890',
    schemaVersion: '1.0.0',
    descriptorDigest: 'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
    bundleDigest: 'sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
);
$planned = Copilot::client()->rpc()->catalog()->planInstallFromReference(
    new CatalogPlanInstallFromReferenceRequest(
        contract: $referenceContract,
        policySessionId: $sessionId,
        reference: $reference,
    ),
);

$plugins = Copilot::client()->rpc()->plugins();
if ($planned->kind === CatalogReferenceInstallationResultKind::Outcome
    && $planned->outcome?->kind === CatalogReferenceInstallationOutcomeKind::PluginInstallPlanned) {
    $plugins->applyInstall(new PluginApplyInstallRequest(
        contract: $referenceContract,
        planHandle: $planned->outcome->plan->planHandle,
        policySessionId: $sessionId,
    ));
} elseif ($planned->kind === CatalogReferenceInstallationResultKind::Outcome
    && $planned->outcome?->kind === CatalogReferenceInstallationOutcomeKind::SkillInstallPlanned) {
    Copilot::client()->rpc()->skills()->applyInstall(new SkillApplyInstallRequest(
        contract: $referenceContract,
        planHandle: $planned->outcome->plan['planHandle'],
        policySessionId: $sessionId,
    ));
}
```

## agentRegistry (experimental: agent registry)

Creates, lists, and removes agent registry entries. The list result doesn't include connection credentials.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\Rpc\AgentRegistryEnsureDirRequest;
use Revolution\Copilot\Types\Rpc\AgentRegistryListEntriesRequest;
use Revolution\Copilot\Types\Rpc\AgentRegistryRemoveEntryRequest;

$homeDir = '/home/user';

$registry = Copilot::client()->rpc()->agentRegistry();
$registry->ensureDir(new AgentRegistryEnsureDirRequest(homeDir: $homeDir));
$entries = $registry->listEntries(new AgentRegistryListEntriesRequest(homeDir: $homeDir));
$registry->removeEntry(new AgentRegistryRemoveEntryRequest(
    homeDir: $homeDir,
    pid: 1234,
));
```

## LSP (server-wide language server settings)

`lsp()` lists the server-wide language server settings. For per-session initialization, start, stop, and similar operations, use `lsp()` on SessionRpc (for usage examples, see [Workspaces, agents, Fleet, and skills](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc/session-workspace.md)).

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

// List server-wide language server settings
$serverConfigs = Copilot::client()->rpc()->lsp()->list([
    'workingDirectory' => base_path(),
]);
```


## Related topics

- [ServerRpc overview](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc/server-overview.md)
- [RPC (Remote Procedure Call)](https://kawax.biz/en/packages/laravel-copilot-sdk/rpc.md)
- [laravel/agent-skills — Laravel's official AI agent skills](https://kawax.biz/en/blog/agent-skills-introduction.md)
- [Plugin Directories](https://kawax.biz/en/packages/laravel-copilot-sdk/plugin-directories.md)
- [Creating a Custom Agent for Boost](https://kawax.biz/en/advanced/boost-custom-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.