> ## 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, instrucciones y extensiones

> Usa ServerRpc en Laravel Copilot SDK para gestionar skills, plugins, agents, instrucciones, extensiones y la configuración de LSP.

## Skills, Plugins, Agents, Instructions y Extensions

Ámbito: ServerRpc (operaciones de todo el servidor vinculadas al Client)

Para una visión general de RPC y la lista de todas las páginas de RPC, consulta [RPC](https://kawax.biz/es/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 (gestión de skills a nivel de servidor)
// Explorar skills
$result = Copilot::client()->rpc()->skills()->discover();
// $result->skills es un array de ServerSkill
// Opcionalmente, indicar rutas de proyecto
$result = Copilot::client()->rpc()->skills()->discover(new SkillsDiscoverRequest(
    projectPaths: ['/path/to/project'],
    skillDirectories: ['/custom/skills'],
));

// Configurar las skills que se desactivan
Copilot::client()->rpc()->skills()->config()->setDisabledSkills(
    new SkillsConfigSetDisabledSkillsRequest(disabledSkills: ['skill-name'])
);

// Activar o desactivar skills individuales
Copilot::client()->rpc()->skills()->config()->setSkillDisabled(
    new SkillsConfigSetSkillDisabledRequest(name: 'skill-name', disabled: true)
);

// Instalar directamente desde una URL HTTPS o un archivo local (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',
));
// Persistir en el lado del llamador los skillDirectories devueltos
$skillDirectories = $installed->skillDirectories;

// Anular el registro de un directorio de descubrimiento. El contenido del directorio no se elimina
$removed = $skills->removeSource(new SkillsRemoveSourceRequest(
    target: '/custom/skills',
    cwd: '/workspace',
    skillDirectories: $skillDirectories,
));
if ($removed->kind === SkillsRemoveSourceOutcomeKind::Removed) {
    $skillDirectories = $removed->result->skillDirectories;
}
// Si eliminar archivos requiere un inventario y lo omites, se devuelve needs-inventory y no cambia nada

// Seleccionar un candidato de skill con catalog.search → catalog.select (experimental)

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

// Obtener recomendaciones de productos oficiales a partir de un nombre de producto y una tarea completa (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,
));

// El category filter requiere catalog-search-categories
$categoryContract = new CatalogClientContract(3, [
    CatalogCapability::CatalogSearchCategories->value,
]);
$categorySearch = $catalog->search(new CatalogSearchRequest(
    contract: $categoryContract,
    query: 'design tools',
    categories: ['design', 'test'],
));
// Si indicas policySessionId, el contract también debe requerir credential-required y session-bound,
// y solo se vincula a una attached session existente. Nunca crea ni reanuda una session.

// catalog feed guardado y generado (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],
));

// Para vincular a una attached session existente, requiere también la capability session-bound
$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 conserva el orden del feed. Las que no coinciden con el trust tier mantienen su posición como filtered,
// y las entry que no se pueden mostrar se devuelven con unavailable y reason.
// Si no hay feed, kind=unavailable y reason=feed-not-found. Los rechazos por autenticación, negociación o política
// también se devuelven como resultados tipados, y las RPC de catalog feed no instalan ni configuran nada.

// Planificar y aplicar la instalación de skills

$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() se aplica tras la confirmación mediante installations.confirm
        $result = $skills->applyInstall(new SkillApplyInstallRequest(
            contract: $contract,
            planHandle: $planned->outcome->plan['planHandle'],
            policySessionId: $sessionId,
        ));
    }
}

// Skills instaladas y operaciones en curso
$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,
));

// La desinstalación también se aplica tras revisar el 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: obtener los directorios donde se pueden crear skills (experimental)
// Lista de directorios que el runtime reconoce al colocar skills en ellos

$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths();
// $result->paths es un array de SkillDiscoveryPath
// $result->paths[0]->path - ruta del directorio
// $result->paths[0]->scope - ámbito (user, project, plugin)
// $result->paths[0]->preferredForCreation - si es el directorio recomendado para crear nuevos
// Opcionalmente, filtrar por ámbito
$result = Copilot::client()->rpc()->skills()->getDiscoveryPaths(
    new SkillsGetDiscoveryPathsRequest(scope: 'project')
);

// plugins (gestión de plugins con ámbito de servidor)

$plugins = Copilot::client()->rpc()->plugins();
$result = $plugins->list(); // Devuelve un 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']));
// Para distinguir instalaciones directas con el mismo nombre, indica en names el directSourceId de list()
$plugins->enable(new PluginsEnableRequest(names: ['opaque-direct-source-id']));
$plugins->disable(new PluginsDisableRequest(names: ['opaque-direct-source-id']));

// Configuración de directorios de plugins integrados
$plugins->builtin()->set(new PluginsBuiltinSetRequest(paths: ['/opt/copilot/plugins']));

// Si indicas en la configuración del cliente los directorios que usan todas las sesiones,
// Client::start() los registra automáticamente antes de crear la primera sesión
// config/copilot.php: 'builtin_plugin_directories' => ['/opt/copilot/plugins']

// Gestión de marketplaces
$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: gestión de agentes personalizados)
// Explorar agentes personalizados

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

// Obtener los directorios donde se pueden crear agentes (experimental)

$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths();
// $result->paths es un array de AgentDiscoveryPath
// $result->paths[0]->path - ruta del directorio
// $result->paths[0]->scope - ámbito (user, project, plugin)
// $result->paths[0]->preferredForCreation - si es el directorio recomendado para crear nuevos
$result = Copilot::client()->rpc()->agents()->getDiscoveryPaths(
    new AgentsGetDiscoveryPathsRequest(scope: 'user')
);

// instructions (experimental: gestión de instrucciones)
// Explorar instrucciones

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

// Obtener los ficheros/directorios donde se pueden crear instrucciones (experimental)

$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths();
// $result->paths es un array de InstructionDiscoveryPath
// $result->paths[0]->path - ruta del fichero/directorio
// $result->paths[0]->location - ubicación (user, repository, working-directory, plugin)
// $result->paths[0]->kind - tipo (file, directory)
// $result->paths[0]->preferredForCreation - si es la recomendada para crear nuevas
$result = Copilot::client()->rpc()->instructions()->getDiscoveryPaths(
    new InstructionsGetDiscoveryPathsRequest(location: 'repository')
);

// extensions (experimental: gestión de extensiones persistidas)
$result = Copilot::client()->rpc()->extensions()->discover();
Copilot::client()->rpc()->extensions()->enable(['ids' => ['user:demo']]);
Copilot::client()->rpc()->extensions()->disable(['ids' => ['plugin:demo']]);
```

## Candidatos de Agent Plugin en el catálogo

Si en `catalog.search` requieres `agent-plugin-discovery` e indicas `plugin` en los `kinds` de búsqueda, puedes obtener candidatos de Agent Plugin. Para recibir `application/vnd.anthropic.claude-plugin+json` y `application/agent-plugin+json`, además del formato estándar `application/vnd.github.copilot-plugin`, requiere `agent-plugin-formats` además de `agent-plugin-discovery`.

`agent-plugin-confirmed-installation` es una capability que devuelve si se puede instalar y un plan para revisión; también se requiere junto con `agent-plugin-discovery`. Si se concede, los candidatos incluyen `installability`, cuyo valor es `installable`, `install-data-unavailable`, `feature-disabled` o `not-installable-kind`. `installPlan` solo se incluye cuando `installability` es `installable`. El plan es solo un dato para revisión; esta RPC de catalog nunca ejecuta la instalación.

Los `sources` del plan contienen, por orden de prioridad, candidatos `materialization`, `marketplace` y `repository`. En Marketplace se registran el nombre y el repositorio, y en un Repository directo, el repositorio y una ruta opcional. En los planes que solo tienen materialization se omite `pluginName` y `components` está vacío. Confirma el nombre y el contenido que se instalará realmente en la revisión que devuelve `plugins.planInstall()`.

Con `plugins.planInstall()` puedes crear, para un candidato seleccionado, un plan validado sin efectos secundarios. `plugins.applyInstall()` solicita una confirmación explícita al usuario y aplica el plan si se autoriza. Tras aplicarlo, el plugin queda registrado en estado desactivado.

Los `mcpServers` de la revisión muestran el nombre del servidor, el transport y, si es remoto, el host que declaran los ficheros validados. Esto no es una garantía de seguridad, así que el usuario debe revisar el contenido antes de dar la confirmación explícita. La `description` de un plugin instalado procede del manifest. `verifiedSource` indica el repositorio de GitHub y un commit fijo, y solo existe en instalaciones directas fijadas a un commit. `iconUrl` es contenido externo no fiable, así que no envíes credenciales ni credenciales de GitHub al obtenerlo. Las credenciales en sí no se devuelven como motivo de rechazo.

En el `network-failure` de un resultado de instalación puedes consultar `CatalogNetworkFailureReason`, el `statusCode` HTTP, un `retryAfterSeconds` opcional y un `message` que se puede mostrar con seguridad.

```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,
    ));
}
```

Para planificar a partir de un materialisation reference de Agent Finder, usa `catalog.planInstallFromReference()`. El `outcome->kind` del resultado es `plugin-install-planned`, `skill-install-planned` o `refused`. Pasa los planes de plugins a `plugins.applyInstall()` y los de skills a `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: registro de agentes)

Crea, lista y elimina entradas del registro de agentes. El resultado de la lista no incluye credenciales de conexión.

```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 (configuración de language servers de todo el servidor)

`lsp()` lista la configuración de language servers de todo el servidor. Para la inicialización, el inicio, la detención y operaciones similares por sesión, usa `lsp()` de SessionRpc (para ver ejemplos de uso, consulta [Workspaces, agents, Fleet y skills](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc/session-workspace.md)).

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

// Listar la configuración de language servers de todo el servidor
$serverConfigs = Copilot::client()->rpc()->lsp()->list([
    'workingDirectory' => base_path(),
]);
```


## Related topics

- [Resumen de ServerRpc](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc/server-overview.md)
- [RPC (Remote Procedure Call)](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc.md)
- [laravel/agent-skills — Colección oficial de skills para agentes de IA de Laravel](https://kawax.biz/es/blog/agent-skills-introduction.md)
- [Plugins y extensiones](https://kawax.biz/es/packages/laravel-copilot-sdk/rpc/session-plugins.md)
- [Skills](https://kawax.biz/es/packages/laravel-copilot-sdk/skills.md)


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