diff --git a/packages/docs-mcp/src/generated/docs-data.json b/packages/docs-mcp/src/generated/docs-data.json index 31e3c40..d691598 100644 --- a/packages/docs-mcp/src/generated/docs-data.json +++ b/packages/docs-mcp/src/generated/docs-data.json @@ -469,6 +469,20 @@ ], "content": "\n# AI at ACTA\n\nThis section brings together everything about artificial intelligence and ACTA: how to connect AI assistants to ACTA's documentation and APIs, and how to use verifiable credentials as a trust layer for AI agents.\n\n## Two ways to use AI with ACTA\n\nThere are two distinct axes, and it helps to keep them separate:\n\n1. **AI on top of ACTA.** You use an assistant (Claude, Cursor, VS Code, Windsurf, or another) to build on ACTA faster: ask how the SDK works, generate snippets, understand errors, or verify credentials through tools.\n2. **Credentials for agents.** You use ACTA to give AI agents their own identity and verifiable credentials, so they can prove who they are, what permissions they hold, and who operates them.\n\n## AI on top of ACTA\n\nThe entry point is the **documentation MCP server** (`@acta-team/docs-mcp`), which exposes ACTA's official, up-to-date documentation to any client that speaks [Model Context Protocol](https://modelcontextprotocol.io). With it, the assistant answers questions about ACTA grounded in real sources instead of generic model knowledge.\n\nOn top of that you can give a model **read-only tools** against the ACTA API (for example, verifying a credential) using function calling. Issuance, signing, and wallet access should never be left to the model autonomously.\n\n## Credentials for agents\n\nThe same primitives ACTA offers for people and organizations (`did:stellar` DIDs, vaults, and verifiable credentials) apply to AI agents. An agent can hold its own DID, carry credentials that declare its operator and permissions, and present them verifiably to other services or agents.\n\nSee [Identity for AI Agents](/en/agent-identity) for the conceptual detail and integration patterns.\n\n## What is in this section\n\n- **[MCP](/en/mcp):** the read-only documentation server and its base configuration.\n- **[MCP Client Setup](/en/mcp-clients):** ready-to-paste blocks for Claude, Cursor, VS Code, and Windsurf, plus troubleshooting.\n- **[Prompt Recipes](/en/ai-prompts):** concrete examples to get the most out of the MCP.\n- **[Identity for AI Agents](/en/agent-identity):** verifiable credentials applied to agents.\n\n## Security principles\n\n- The documentation MCP is **read-only**: it does not issue credentials, sign transactions, or access wallets.\n- When exposing API tools to a model, scope them to read operations unless a human approves every sensitive action.\n- Treat any configurable context source (for example `ACTA_DOCS_MCP_DATA_URL`) as trusted only if you control its origin.\n " }, + "agent-skills": { + "slug": "agent-skills", + "title": "Agent Skills", + "section": "AI", + "tocItems": [ + "What it is", + "Install", + "What the skill covers", + "How it works", + "Skill vs MCP", + "Source of truth" + ], + "content": "\n# Agent Skills\n\nThe **ACTA Agent Skill** teaches an AI coding agent how to build with ACTA correctly. It is published as an open [Agent Skill](https://www.skills.sh) that installs into Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini, and other MCP or skill-compatible agents.\n\nUse it when you want your coding agent to write ACTA integrations without guessing: the right package name, base URLs, the prepare/submit flow, `did:stellar` issuer identity, error codes, and the security model all come from the official docs instead of stale training data.\n\n- **Directory:** [skills.sh/ACTA-Team/skills](https://www.skills.sh/ACTA-Team/skills)\n- **Source:** [github.com/ACTA-Team/skills](https://github.com/ACTA-Team/skills)\n\n## What it is\n\nA skill is a reusable folder (a `SKILL.md` plus references and examples) that an agent loads as context. The agent reads the skill's description, decides it is relevant to your ACTA task, and follows its instructions in place of guessing. See [AI Overview](doc:ai-overview) for how skills fit next to the other AI tooling.\n\n## Install\n\nInstall into any supported agent with the skills CLI:\n\n```bash\n# Install every skill in the repo\nnpx skills add ACTA-Team/skills\n\n# Or install just the acta skill\nnpx skills add ACTA-Team/skills/acta\n```\n\nThe CLI writes the skill into your agent's skills directory (for example `.claude/skills/` for Claude Code) and the agent picks it up automatically. See the [skills.sh docs](https://www.skills.sh/docs) for per-agent details.\n\nYou can also copy the `acta/` folder from the repo directly into your agent's skills directory.\n\n## What the skill covers\n\n- The `@acta-team/credentials` React SDK: `ActaConfig`, `useCredential`, `useVault`, `useVaultRead`, `useActaClient`, and `ActaClient`.\n- The REST API: `/contracts/*` endpoints, the `X-ACTA-Key` header, the prepare/submit XDR flow, ownership rules, rate limits, and idempotency.\n- `did:stellar` issuer and holder identity, resolution, and issuer verification.\n- Vaults: single-tenant, deterministic addressing, sponsored vaults, and push.\n- Error handling: HTTP codes, validation, issuer-DID errors, contract errors, and the mainnet USDC fee failures.\n- The security and data model: who signs what, what is on-chain versus encrypted.\n\nThe skill is structured for progressive disclosure: a concise `SKILL.md` entry point, with deeper material in `references/` and runnable code in `examples/`.\n\n## How it works\n\n[skills.sh](https://www.skills.sh) has no separate publish step. A repository is indexed automatically through anonymous install telemetry the first time someone runs `npx skills add ACTA-Team/skills`. The more it is installed, the higher it ranks in the directory.\n\n## Skill vs MCP\n\nThe skill and the [MCP server](doc:mcp) are complementary:\n\n- The **skill** ships opinionated, ready-to-use integration guidance that the agent follows while writing code.\n- The **MCP** (`@acta-team/docs-mcp`) lets the agent query the live official documentation on demand.\n\nInstall both for the best result: the skill for how to build, the MCP for looking things up.\n\n## Source of truth\n\nThe skill is distilled from the official documentation at [docs.acta.build](https://docs.acta.build). When a detail in the skill conflicts with the live docs, the live docs win.\n " + }, "mcp": { "slug": "mcp", "title": "MCP", @@ -1044,6 +1058,20 @@ ], "content": "\n# IA en ACTA\n\nEsta sección reúne todo lo relacionado con inteligencia artificial y ACTA: cómo conectar asistentes de IA a la documentación y a las APIs de ACTA, y cómo usar credenciales verificables como capa de confianza para agentes de IA.\n\n## Dos formas de usar IA con ACTA\n\nHay dos ejes distintos, y conviene tenerlos claros:\n\n1. **IA sobre ACTA.** Usas un asistente (Claude, Cursor, VS Code, Windsurf u otro) para construir sobre ACTA más rápido: preguntar cómo funciona el SDK, generar snippets, entender errores o verificar credenciales mediante herramientas.\n2. **Credenciales para agentes.** Usas ACTA para dar identidad y credenciales verificables a los propios agentes de IA, de modo que puedan probar quiénes son, qué permisos tienen y quién los opera.\n\n## IA sobre ACTA\n\nEl punto de entrada es el **servidor MCP de documentación** (`@acta-team/docs-mcp`), que expone la documentación oficial y actualizada de ACTA a cualquier cliente compatible con [Model Context Protocol](https://modelcontextprotocol.io). Con él, el asistente responde sobre ACTA apoyándose en fuentes reales en lugar de conocimiento genérico.\n\nEncima de eso puedes darle a un modelo **herramientas de solo lectura** contra la API de ACTA (por ejemplo, verificar una credencial) usando function calling. La emisión, la firma y el acceso a wallets nunca deben quedar en manos autónomas del modelo.\n\n## Credenciales para agentes\n\nLos mismos primitivos que ACTA ofrece para personas y organizaciones (DIDs `did:stellar`, bóvedas y credenciales verificables) aplican a agentes de IA. Un agente puede tener su propio DID, portar credenciales que declaren su operador y sus permisos, y presentarlas de forma verificable ante otros servicios o agentes.\n\nConsulta [Identidad para agentes de IA](/es/agent-identity) para el detalle conceptual y los patrones de integración.\n\n## Qué hay en esta sección\n\n- **[MCP](/es/mcp):** el servidor de documentación de solo lectura y su configuración base.\n- **[Configuración por cliente](/es/mcp-clients):** bloques listos para Claude, Cursor, VS Code y Windsurf, más troubleshooting.\n- **[Recetas de prompts](/es/ai-prompts):** ejemplos concretos para sacarle provecho al MCP.\n- **[Identidad para agentes de IA](/es/agent-identity):** credenciales verificables aplicadas a agentes.\n\n## Principios de seguridad\n\n- El MCP de documentación es **solo lectura**: no emite credenciales, no firma transacciones y no accede a wallets.\n- Al exponer herramientas de API a un modelo, limita el alcance a operaciones de lectura salvo que haya un humano aprobando cada acción sensible.\n- Trata cualquier fuente de contexto configurable (por ejemplo `ACTA_DOCS_MCP_DATA_URL`) como confiable solo si tú controlas su origen.\n " }, + "agent-skills": { + "slug": "agent-skills", + "title": "Agent Skills", + "section": "AI", + "tocItems": [ + "Qué es", + "Instalación", + "Qué cubre la skill", + "Cómo funciona", + "Skill vs MCP", + "Fuente de verdad" + ], + "content": "\n# Agent Skills\n\nLa **Agent Skill de ACTA** le enseña a un agente de IA de programación a construir con ACTA de forma correcta. Se publica como una [Agent Skill](https://www.skills.sh) abierta que se instala en Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini y otros agentes compatibles con MCP o con skills.\n\nÚsala cuando quieras que tu agente escriba integraciones de ACTA sin adivinar: el nombre correcto del paquete, las URLs base, el flujo prepare/submit, la identidad de emisor `did:stellar`, los códigos de error y el modelo de seguridad salen de la documentación oficial y no de datos de entrenamiento desactualizados.\n\n- **Directorio:** [skills.sh/ACTA-Team/skills](https://www.skills.sh/ACTA-Team/skills)\n- **Código:** [github.com/ACTA-Team/skills](https://github.com/ACTA-Team/skills)\n\n## Qué es\n\nUna skill es una carpeta reutilizable (un `SKILL.md` más referencias y ejemplos) que el agente carga como contexto. El agente lee la descripción de la skill, decide que es relevante para tu tarea de ACTA y sigue sus instrucciones en lugar de adivinar. Consulta el [Resumen de IA](doc:ai-overview) para ver cómo encajan las skills junto al resto del tooling de IA.\n\n## Instalación\n\nInstálala en cualquier agente compatible con el CLI de skills:\n\n```bash\n# Instalar todas las skills del repo\nnpx skills add ACTA-Team/skills\n\n# O solo la skill acta\nnpx skills add ACTA-Team/skills/acta\n```\n\nEl CLI escribe la skill en el directorio de skills de tu agente (por ejemplo `.claude/skills/` en Claude Code) y el agente la toma automáticamente. Consulta la [documentación de skills.sh](https://www.skills.sh/docs) para detalles por agente.\n\nTambién puedes copiar la carpeta `acta/` del repo directamente en el directorio de skills de tu agente.\n\n## Qué cubre la skill\n\n- El SDK de React `@acta-team/credentials`: `ActaConfig`, `useCredential`, `useVault`, `useVaultRead`, `useActaClient` y `ActaClient`.\n- La API REST: endpoints `/contracts/*`, el header `X-ACTA-Key`, el flujo prepare/submit con XDR, reglas de propiedad, límites de tasa e idempotencia.\n- Identidad de emisor y titular con `did:stellar`, resolución y verificación del emisor.\n- Vaults: single-tenant, direccionamiento determinista, vaults patrocinados y push.\n- Manejo de errores: códigos HTTP, validación, errores de issuer-DID, errores de contrato y los fallos de fee en USDC en mainnet.\n- El modelo de seguridad y datos: quién firma qué, qué vive on-chain y qué está cifrado.\n\nLa skill está estructurada para divulgación progresiva: un `SKILL.md` conciso como entrada, con el detalle en `references/` y código ejecutable en `examples/`.\n\n## Cómo funciona\n\n[skills.sh](https://www.skills.sh) no tiene un paso de publicación separado. Un repositorio se indexa automáticamente mediante telemetría anónima de instalación la primera vez que alguien ejecuta `npx skills add ACTA-Team/skills`. Cuanto más se instala, más sube en el directorio.\n\n## Skill vs MCP\n\nLa skill y el [servidor MCP](doc:mcp) son complementarios:\n\n- La **skill** entrega guía de integración lista para usar que el agente sigue mientras escribe código.\n- El **MCP** (`@acta-team/docs-mcp`) le permite al agente consultar la documentación oficial en vivo cuando la necesita.\n\nInstala ambos para el mejor resultado: la skill para saber cómo construir, el MCP para consultar.\n\n## Fuente de verdad\n\nLa skill está destilada de la documentación oficial en [docs.acta.build](https://docs.acta.build). Cuando un detalle de la skill entre en conflicto con la documentación en vivo, manda la documentación en vivo.\n " + }, "mcp": { "slug": "mcp", "title": "MCP", @@ -1606,6 +1634,20 @@ ], "content": "\n# Bibliothèque TypeScript\n\n**`@acta-team/did-stellar`** est la bibliothèque TypeScript officielle pour la méthode did:stellar : utilitaires d'identifiants, résolution W3C, validation d'enregistrements, construction de transactions prepare/submit, Proof of Control, un client HTTP pour `did.acta.build` et un hook React.\n\n## Installation\n\n```bash\nnpm install @acta-team/did-stellar\n```\n\n- Build double **ESM + CJS** avec déclarations TypeScript.\n- Exports de sous-chemins : `@acta-team/did-stellar/resolver` (résolution uniquement, bundle plus petit) et `@acta-team/did-stellar/hooks` (React).\n- React est une dépendance peer **optionnelle** (nécessaire seulement pour le hook).\n- Fonctionne avec les valeurs par défaut publiques dès l'installation : les URLs RPC Stellar et les identifiants du contrat de registre pour les deux réseaux sont intégrés.\n\n## Contenu\n\n| Domaine | Exports clés |\n|------|-------------|\n| Identifiant | `generateDidId`, `buildDidStellar`, `parseDidStellar`, `isValidDidStellar`, `DID_STELLAR_REGEX` |\n| Résolution | `resolveDidStellar`, `getResolver` (driver DIF `did-resolver`) |\n| Enregistrement | `validateDidRecordInput`, `readDidRecord`, `DID_RECORD_LIMITS`, types `DidRecord`, `DidKey`, `DidService` |\n| Clés | `encodeMultikey`, `decodeMultikey`, `detectCurve` (Ed25519 / X25519) |\n| Transactions | `prepareRegisterDidXdr`, `prepareUpdateDidXdr`, `prepareTransferControllerXdr`, `prepareDeactivateDidXdr`, `submitSignedXdr` |\n| Proof of Control | `buildChallenge`, `generateNonce`, `jcsCanonicalize`, `verifyProofOfControl` |\n| Client HTTP | `ActaDidClient` (enveloppe did.acta.build) |\n| React | Hook `useDid()` |\n| Erreurs | `DidError` avec des chaînes `code` stables |\n\n## Enregistrer un DID\n\nLe flux self-service canonique : générer les clés, préparer le XDR, signer avec le wallet du contrôleur, soumettre.\n\n```ts\nimport {\n generateDidId,\n buildDidStellar,\n encodeMultikey,\n prepareRegisterDidXdr,\n submitSignedXdr,\n} from \"@acta-team/did-stellar\";\nimport * as ed from \"@noble/ed25519\";\n\n// 1. Générer une clé Ed25519 pour le DID\nconst privateKey = ed.utils.randomPrivateKey();\nconst publicKey = await ed.getPublicKeyAsync(privateKey);\nconst publicKeyMultibase = encodeMultikey(\"Ed25519\", publicKey);\n\n// 2. Créer le DID et préparer la transaction d'enregistrement\nconst did = buildDidStellar(\"testnet\", generateDidId());\nconst prepared = await prepareRegisterDidXdr({\n did,\n sourcePublicKey: \"G...\", // le wallet du contrôleur\n record: {\n controller: \"G...\",\n authentication: [{ publicKeyMultibase }],\n assertionMethod: [{ publicKeyMultibase }], // les émetteurs en ont besoin\n keyAgreement: [],\n services: [],\n },\n});\n\n// 3. Signer avec votre wallet, puis soumettre\nconst signedXdr = await signTransaction(prepared.xdr, {\n networkPassphrase: prepared.networkPassphrase,\n});\nconst { txId } = await submitSignedXdr({ signedXdr, network: \"testnet\" });\n```\n\nLe wallet du contrôleur signe la **transaction** ; la clé Ed25519 va **dans l'enregistrement** et c'est elle qui signera plus tard les credentials. Les émetteurs doivent inclure au moins une clé `assertionMethod`.\n\n`update`, `transfer` et `deactivate` suivent la même forme avec leurs équivalents `prepare*Xdr` plus `expectedVersion`.\n\n## Résoudre un DID\n\n```ts\nimport { resolveDidStellar } from \"@acta-team/did-stellar/resolver\";\n\nconst result = await resolveDidStellar(\n \"did:stellar:testnet:znfxngsh46vkyqu6inrx4omphi\"\n);\n// result.didDocument, result.didDocumentMetadata, result.didResolutionMetadata\n```\n\nPour les écosystèmes construits sur le package DIF `did-resolver` :\n\n```ts\nimport { Resolver } from \"did-resolver\";\nimport { getResolver } from \"@acta-team/did-stellar/resolver\";\n\nconst resolver = new Resolver({ ...getResolver() });\nconst result = await resolver.resolve(\"did:stellar:mainnet:...\");\n```\n\nLes deux acceptent des remplacements de `rpcUrl` et `registryContractId` par réseau.\n\n## Hook React (useDid)\n\n```ts\nimport { useDid } from \"@acta-team/did-stellar/hooks\";\n\nconst { register, update, transfer, deactivate, resolve, getRecord } =\n useDid();\n\nconst { txId } = await register({\n did,\n sourcePublicKey: \"G...\",\n record,\n sign: async (xdr, { networkPassphrase }) => {\n // n'importe quel wallet Stellar : Freighter, Albedo, WalletConnect...\n return signedXdr;\n },\n});\n```\n\nChaque mutation prend les arguments du prepare plus un callback `sign` indépendant du wallet, et retourne `{ txId }`.\n\n## Client HTTP (ActaDidClient)\n\nUn client léger pour le resolver hébergé, utile quand vous préférez HTTP au RPC direct :\n\n```ts\nimport { ActaDidClient } from \"@acta-team/did-stellar\";\n\nconst client = new ActaDidClient({ baseUrl: \"https://did.acta.build\" });\n\nconst resolution = await client.resolve(did);\nconst record = await client.getDidRecord(did);\nconst prepared = await client.prepareRegister({\n record,\n network: \"testnet\",\n sourcePublicKey: \"G...\",\n});\nconst { txId } = await client.submit({ signedXdr });\n```\n\n## Proof of Control\n\nVérifiez qu'une partie contrôle un DID (par exemple pour la connexion par DID) sans aucune transaction :\n\n```ts\nimport {\n buildChallenge,\n generateNonce,\n verifyProofOfControl,\n} from \"@acta-team/did-stellar\";\n\n// Côté vérificateur\nconst challenge = buildChallenge({\n did,\n domain: \"myapp.com\",\n nonce: generateNonce(),\n});\n\n// ...le signataire canonicalise (JCS) et signe avec une clé authentication...\n\nconst result = await verifyProofOfControl({\n challenge,\n signature,\n isNonceFresh: async nonce => myNonceStore.checkAndBurn(nonce),\n});\n// result: { valid, reason?, matchedKeyId? }\n```\n\nLes vérifications s'exécutent dans l'ordre de la spécification : timestamp dans une fenêtre de 5 minutes, correspondance du domaine, fraîcheur du nonce (magasin enfichable), puis la signature Ed25519 contre chaque clé `authentication`.\n\n## Validation et erreurs\n\n- `validateDidRecordInput(record)` reflète la validation du contrat règle par règle, ce qui vous permet d'échouer rapidement **avant** tout appel réseau.\n- Chaque échec est une `DidError` avec un `code` stable (`did_invalid`, `did_already_exists`, `version_mismatch`, `did_deactivated`, `multikey_unsupported`, `tx_submission_failed`, ...), les mêmes codes que l'API du resolver retourne. Branchez-vous sur `code`, jamais sur `message`.\n\n## Relation avec le Credentials SDK\n\n- **`@acta-team/credentials` s'appuie sur cette bibliothèque** pour l'auto-onboarding des émetteurs : le premier appel `issue` sans `issuerDid` génère une clé Ed25519, enregistre un did:stellar (la même clé dans `authentication` et `assertionMethod`) avec une seule signature de wallet, et persiste l'identité. Voir **[Credentials SDK](doc:sdk-overview)**.\n- Utilisez `@acta-team/did-stellar` directement quand vous avez besoin d'un contrôle total sur les clés, les enregistrements, les services, la rotation de clés ou la connexion par DID.\n- L'API de credentials d'ACTA n'importe délibérément **pas** cette bibliothèque : identité et credentials sont des domaines de confiance séparés.\n " }, + "agent-skills": { + "slug": "agent-skills", + "title": "Agent Skills", + "section": "AI", + "tocItems": [ + "Ce que c'est", + "Installation", + "Ce que couvre la skill", + "Comment ça marche", + "Skill vs MCP", + "Source de vérité" + ], + "content": "\n# Agent Skills\n\nL'**Agent Skill ACTA** apprend à un agent de codage IA à construire correctement avec ACTA. Elle est publiée comme une [Agent Skill](https://www.skills.sh) ouverte qui s'installe dans Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini et d'autres agents compatibles MCP ou skills.\n\nUtilisez-la pour que votre agent écrive des intégrations ACTA sans deviner : le bon nom de paquet, les URLs de base, le flux prepare/submit, l'identité d'émetteur `did:stellar`, les codes d'erreur et le modèle de sécurité proviennent de la documentation officielle et non de données d'entraînement obsolètes.\n\n- **Répertoire :** [skills.sh/ACTA-Team/skills](https://www.skills.sh/ACTA-Team/skills)\n- **Source :** [github.com/ACTA-Team/skills](https://github.com/ACTA-Team/skills)\n\n## Ce que c'est\n\nUne skill est un dossier réutilisable (un `SKILL.md` plus des références et des exemples) que l'agent charge comme contexte. L'agent lit la description de la skill, décide qu'elle est pertinente pour votre tâche ACTA, et suit ses instructions au lieu de deviner. Voir l'[Aperçu de l'IA](doc:ai-overview) pour situer les skills parmi les autres outils IA.\n\n## Installation\n\nInstallez-la dans n'importe quel agent compatible avec le CLI skills :\n\n```bash\n# Installer toutes les skills du dépôt\nnpx skills add ACTA-Team/skills\n\n# Ou seulement la skill acta\nnpx skills add ACTA-Team/skills/acta\n```\n\nLe CLI écrit la skill dans le répertoire de skills de votre agent (par exemple `.claude/skills/` pour Claude Code) et l'agent la prend en compte automatiquement. Voir la [documentation skills.sh](https://www.skills.sh/docs) pour les détails par agent.\n\nVous pouvez aussi copier le dossier `acta/` du dépôt directement dans le répertoire de skills de votre agent.\n\n## Ce que couvre la skill\n\n- Le SDK React `@acta-team/credentials` : `ActaConfig`, `useCredential`, `useVault`, `useVaultRead`, `useActaClient` et `ActaClient`.\n- L'API REST : endpoints `/contracts/*`, l'en-tête `X-ACTA-Key`, le flux prepare/submit XDR, les règles de propriété, les limites de débit et l'idempotence.\n- L'identité d'émetteur et de titulaire `did:stellar`, la résolution et la vérification de l'émetteur.\n- Les vaults : single-tenant, adressage déterministe, vaults sponsorisés et push.\n- La gestion des erreurs : codes HTTP, validation, erreurs issuer-DID, erreurs de contrat et les échecs de frais USDC sur mainnet.\n- Le modèle de sécurité et de données : qui signe quoi, ce qui est on-chain versus chiffré.\n\nLa skill est structurée pour une divulgation progressive : un `SKILL.md` concis comme point d'entrée, avec le détail dans `references/` et du code exécutable dans `examples/`.\n\n## Comment ça marche\n\n[skills.sh](https://www.skills.sh) n'a pas d'étape de publication séparée. Un dépôt est indexé automatiquement via une télémétrie d'installation anonyme la première fois que quelqu'un exécute `npx skills add ACTA-Team/skills`. Plus elle est installée, plus elle monte dans le répertoire.\n\n## Skill vs MCP\n\nLa skill et le [serveur MCP](doc:mcp) sont complémentaires :\n\n- La **skill** fournit des conseils d'intégration prêts à l'emploi que l'agent suit pendant qu'il écrit du code.\n- Le **MCP** (`@acta-team/docs-mcp`) permet à l'agent d'interroger la documentation officielle en direct à la demande.\n\nInstallez les deux pour un résultat optimal : la skill pour savoir comment construire, le MCP pour la consultation.\n\n## Source de vérité\n\nLa skill est distillée de la documentation officielle sur [docs.acta.build](https://docs.acta.build). Lorsqu'un détail de la skill entre en conflit avec la documentation en direct, la documentation en direct prévaut.\n " + }, "mcp": { "slug": "mcp", "title": "MCP", diff --git a/src/content/docs/modules/mcp/en/agent-skills.ts b/src/content/docs/modules/mcp/en/agent-skills.ts new file mode 100644 index 0000000..6d3e8da --- /dev/null +++ b/src/content/docs/modules/mcp/en/agent-skills.ts @@ -0,0 +1,73 @@ +import type { DocPage } from "@/@types/docs"; + +export const agentSkills: DocPage = { + slug: "agent-skills", + title: "Agent Skills", + section: "AI", + tocItems: [ + "What it is", + "Install", + "What the skill covers", + "How it works", + "Skill vs MCP", + "Source of truth", + ], + content: ` +# Agent Skills + +The **ACTA Agent Skill** teaches an AI coding agent how to build with ACTA correctly. It is published as an open [Agent Skill](https://www.skills.sh) that installs into Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini, and other MCP or skill-compatible agents. + +Use it when you want your coding agent to write ACTA integrations without guessing: the right package name, base URLs, the prepare/submit flow, \`did:stellar\` issuer identity, error codes, and the security model all come from the official docs instead of stale training data. + +- **Directory:** [skills.sh/ACTA-Team/skills](https://www.skills.sh/ACTA-Team/skills) +- **Source:** [github.com/ACTA-Team/skills](https://github.com/ACTA-Team/skills) + +## What it is + +A skill is a reusable folder (a \`SKILL.md\` plus references and examples) that an agent loads as context. The agent reads the skill's description, decides it is relevant to your ACTA task, and follows its instructions in place of guessing. See [AI Overview](doc:ai-overview) for how skills fit next to the other AI tooling. + +## Install + +Install into any supported agent with the skills CLI: + +\`\`\`bash +# Install every skill in the repo +npx skills add ACTA-Team/skills + +# Or install just the acta skill +npx skills add ACTA-Team/skills/acta +\`\`\` + +The CLI writes the skill into your agent's skills directory (for example \`.claude/skills/\` for Claude Code) and the agent picks it up automatically. See the [skills.sh docs](https://www.skills.sh/docs) for per-agent details. + +You can also copy the \`acta/\` folder from the repo directly into your agent's skills directory. + +## What the skill covers + +- The \`@acta-team/credentials\` React SDK: \`ActaConfig\`, \`useCredential\`, \`useVault\`, \`useVaultRead\`, \`useActaClient\`, and \`ActaClient\`. +- The REST API: \`/contracts/*\` endpoints, the \`X-ACTA-Key\` header, the prepare/submit XDR flow, ownership rules, rate limits, and idempotency. +- \`did:stellar\` issuer and holder identity, resolution, and issuer verification. +- Vaults: single-tenant, deterministic addressing, sponsored vaults, and push. +- Error handling: HTTP codes, validation, issuer-DID errors, contract errors, and the mainnet USDC fee failures. +- The security and data model: who signs what, what is on-chain versus encrypted. + +The skill is structured for progressive disclosure: a concise \`SKILL.md\` entry point, with deeper material in \`references/\` and runnable code in \`examples/\`. + +## How it works + +[skills.sh](https://www.skills.sh) has no separate publish step. A repository is indexed automatically through anonymous install telemetry the first time someone runs \`npx skills add ACTA-Team/skills\`. The more it is installed, the higher it ranks in the directory. + +## Skill vs MCP + +The skill and the [MCP server](doc:mcp) are complementary: + +- The **skill** ships opinionated, ready-to-use integration guidance that the agent follows while writing code. +- The **MCP** (\`@acta-team/docs-mcp\`) lets the agent query the live official documentation on demand. + +Install both for the best result: the skill for how to build, the MCP for looking things up. + +## Source of truth + +The skill is distilled from the official documentation at [docs.acta.build](https://docs.acta.build). When a detail in the skill conflicts with the live docs, the live docs win. + `, +}; diff --git a/src/content/docs/modules/mcp/en/index.ts b/src/content/docs/modules/mcp/en/index.ts index 03dd472..dc2f14e 100644 --- a/src/content/docs/modules/mcp/en/index.ts +++ b/src/content/docs/modules/mcp/en/index.ts @@ -1,5 +1,6 @@ import type { DocPage } from "@/@types/docs"; import { aiOverview } from "./ai-overview"; +import { agentSkills } from "./agent-skills"; import { mcp } from "./mcp"; import { mcpClients } from "./mcp-clients"; import { aiPrompts } from "./ai-prompts"; @@ -7,6 +8,7 @@ import { agentIdentity } from "./agent-identity"; export const pages: Record = { "ai-overview": aiOverview, + "agent-skills": agentSkills, mcp, "mcp-clients": mcpClients, "ai-prompts": aiPrompts, diff --git a/src/content/docs/modules/mcp/es/agent-skills.ts b/src/content/docs/modules/mcp/es/agent-skills.ts new file mode 100644 index 0000000..b34c479 --- /dev/null +++ b/src/content/docs/modules/mcp/es/agent-skills.ts @@ -0,0 +1,73 @@ +import type { DocPage } from "@/@types/docs"; + +export const agentSkills: DocPage = { + slug: "agent-skills", + title: "Agent Skills", + section: "AI", + tocItems: [ + "Qué es", + "Instalación", + "Qué cubre la skill", + "Cómo funciona", + "Skill vs MCP", + "Fuente de verdad", + ], + content: ` +# Agent Skills + +La **Agent Skill de ACTA** le enseña a un agente de IA de programación a construir con ACTA de forma correcta. Se publica como una [Agent Skill](https://www.skills.sh) abierta que se instala en Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini y otros agentes compatibles con MCP o con skills. + +Úsala cuando quieras que tu agente escriba integraciones de ACTA sin adivinar: el nombre correcto del paquete, las URLs base, el flujo prepare/submit, la identidad de emisor \`did:stellar\`, los códigos de error y el modelo de seguridad salen de la documentación oficial y no de datos de entrenamiento desactualizados. + +- **Directorio:** [skills.sh/ACTA-Team/skills](https://www.skills.sh/ACTA-Team/skills) +- **Código:** [github.com/ACTA-Team/skills](https://github.com/ACTA-Team/skills) + +## Qué es + +Una skill es una carpeta reutilizable (un \`SKILL.md\` más referencias y ejemplos) que el agente carga como contexto. El agente lee la descripción de la skill, decide que es relevante para tu tarea de ACTA y sigue sus instrucciones en lugar de adivinar. Consulta el [Resumen de IA](doc:ai-overview) para ver cómo encajan las skills junto al resto del tooling de IA. + +## Instalación + +Instálala en cualquier agente compatible con el CLI de skills: + +\`\`\`bash +# Instalar todas las skills del repo +npx skills add ACTA-Team/skills + +# O solo la skill acta +npx skills add ACTA-Team/skills/acta +\`\`\` + +El CLI escribe la skill en el directorio de skills de tu agente (por ejemplo \`.claude/skills/\` en Claude Code) y el agente la toma automáticamente. Consulta la [documentación de skills.sh](https://www.skills.sh/docs) para detalles por agente. + +También puedes copiar la carpeta \`acta/\` del repo directamente en el directorio de skills de tu agente. + +## Qué cubre la skill + +- El SDK de React \`@acta-team/credentials\`: \`ActaConfig\`, \`useCredential\`, \`useVault\`, \`useVaultRead\`, \`useActaClient\` y \`ActaClient\`. +- La API REST: endpoints \`/contracts/*\`, el header \`X-ACTA-Key\`, el flujo prepare/submit con XDR, reglas de propiedad, límites de tasa e idempotencia. +- Identidad de emisor y titular con \`did:stellar\`, resolución y verificación del emisor. +- Vaults: single-tenant, direccionamiento determinista, vaults patrocinados y push. +- Manejo de errores: códigos HTTP, validación, errores de issuer-DID, errores de contrato y los fallos de fee en USDC en mainnet. +- El modelo de seguridad y datos: quién firma qué, qué vive on-chain y qué está cifrado. + +La skill está estructurada para divulgación progresiva: un \`SKILL.md\` conciso como entrada, con el detalle en \`references/\` y código ejecutable en \`examples/\`. + +## Cómo funciona + +[skills.sh](https://www.skills.sh) no tiene un paso de publicación separado. Un repositorio se indexa automáticamente mediante telemetría anónima de instalación la primera vez que alguien ejecuta \`npx skills add ACTA-Team/skills\`. Cuanto más se instala, más sube en el directorio. + +## Skill vs MCP + +La skill y el [servidor MCP](doc:mcp) son complementarios: + +- La **skill** entrega guía de integración lista para usar que el agente sigue mientras escribe código. +- El **MCP** (\`@acta-team/docs-mcp\`) le permite al agente consultar la documentación oficial en vivo cuando la necesita. + +Instala ambos para el mejor resultado: la skill para saber cómo construir, el MCP para consultar. + +## Fuente de verdad + +La skill está destilada de la documentación oficial en [docs.acta.build](https://docs.acta.build). Cuando un detalle de la skill entre en conflicto con la documentación en vivo, manda la documentación en vivo. + `, +}; diff --git a/src/content/docs/modules/mcp/es/index.ts b/src/content/docs/modules/mcp/es/index.ts index 03dd472..dc2f14e 100644 --- a/src/content/docs/modules/mcp/es/index.ts +++ b/src/content/docs/modules/mcp/es/index.ts @@ -1,5 +1,6 @@ import type { DocPage } from "@/@types/docs"; import { aiOverview } from "./ai-overview"; +import { agentSkills } from "./agent-skills"; import { mcp } from "./mcp"; import { mcpClients } from "./mcp-clients"; import { aiPrompts } from "./ai-prompts"; @@ -7,6 +8,7 @@ import { agentIdentity } from "./agent-identity"; export const pages: Record = { "ai-overview": aiOverview, + "agent-skills": agentSkills, mcp, "mcp-clients": mcpClients, "ai-prompts": aiPrompts, diff --git a/src/content/docs/modules/mcp/fr/agent-skills.ts b/src/content/docs/modules/mcp/fr/agent-skills.ts new file mode 100644 index 0000000..e080775 --- /dev/null +++ b/src/content/docs/modules/mcp/fr/agent-skills.ts @@ -0,0 +1,73 @@ +import type { DocPage } from "@/@types/docs"; + +export const agentSkills: DocPage = { + slug: "agent-skills", + title: "Agent Skills", + section: "AI", + tocItems: [ + "Ce que c'est", + "Installation", + "Ce que couvre la skill", + "Comment ça marche", + "Skill vs MCP", + "Source de vérité", + ], + content: ` +# Agent Skills + +L'**Agent Skill ACTA** apprend à un agent de codage IA à construire correctement avec ACTA. Elle est publiée comme une [Agent Skill](https://www.skills.sh) ouverte qui s'installe dans Claude Code, Cursor, GitHub Copilot, Windsurf, Gemini et d'autres agents compatibles MCP ou skills. + +Utilisez-la pour que votre agent écrive des intégrations ACTA sans deviner : le bon nom de paquet, les URLs de base, le flux prepare/submit, l'identité d'émetteur \`did:stellar\`, les codes d'erreur et le modèle de sécurité proviennent de la documentation officielle et non de données d'entraînement obsolètes. + +- **Répertoire :** [skills.sh/ACTA-Team/skills](https://www.skills.sh/ACTA-Team/skills) +- **Source :** [github.com/ACTA-Team/skills](https://github.com/ACTA-Team/skills) + +## Ce que c'est + +Une skill est un dossier réutilisable (un \`SKILL.md\` plus des références et des exemples) que l'agent charge comme contexte. L'agent lit la description de la skill, décide qu'elle est pertinente pour votre tâche ACTA, et suit ses instructions au lieu de deviner. Voir l'[Aperçu de l'IA](doc:ai-overview) pour situer les skills parmi les autres outils IA. + +## Installation + +Installez-la dans n'importe quel agent compatible avec le CLI skills : + +\`\`\`bash +# Installer toutes les skills du dépôt +npx skills add ACTA-Team/skills + +# Ou seulement la skill acta +npx skills add ACTA-Team/skills/acta +\`\`\` + +Le CLI écrit la skill dans le répertoire de skills de votre agent (par exemple \`.claude/skills/\` pour Claude Code) et l'agent la prend en compte automatiquement. Voir la [documentation skills.sh](https://www.skills.sh/docs) pour les détails par agent. + +Vous pouvez aussi copier le dossier \`acta/\` du dépôt directement dans le répertoire de skills de votre agent. + +## Ce que couvre la skill + +- Le SDK React \`@acta-team/credentials\` : \`ActaConfig\`, \`useCredential\`, \`useVault\`, \`useVaultRead\`, \`useActaClient\` et \`ActaClient\`. +- L'API REST : endpoints \`/contracts/*\`, l'en-tête \`X-ACTA-Key\`, le flux prepare/submit XDR, les règles de propriété, les limites de débit et l'idempotence. +- L'identité d'émetteur et de titulaire \`did:stellar\`, la résolution et la vérification de l'émetteur. +- Les vaults : single-tenant, adressage déterministe, vaults sponsorisés et push. +- La gestion des erreurs : codes HTTP, validation, erreurs issuer-DID, erreurs de contrat et les échecs de frais USDC sur mainnet. +- Le modèle de sécurité et de données : qui signe quoi, ce qui est on-chain versus chiffré. + +La skill est structurée pour une divulgation progressive : un \`SKILL.md\` concis comme point d'entrée, avec le détail dans \`references/\` et du code exécutable dans \`examples/\`. + +## Comment ça marche + +[skills.sh](https://www.skills.sh) n'a pas d'étape de publication séparée. Un dépôt est indexé automatiquement via une télémétrie d'installation anonyme la première fois que quelqu'un exécute \`npx skills add ACTA-Team/skills\`. Plus elle est installée, plus elle monte dans le répertoire. + +## Skill vs MCP + +La skill et le [serveur MCP](doc:mcp) sont complémentaires : + +- La **skill** fournit des conseils d'intégration prêts à l'emploi que l'agent suit pendant qu'il écrit du code. +- Le **MCP** (\`@acta-team/docs-mcp\`) permet à l'agent d'interroger la documentation officielle en direct à la demande. + +Installez les deux pour un résultat optimal : la skill pour savoir comment construire, le MCP pour la consultation. + +## Source de vérité + +La skill est distillée de la documentation officielle sur [docs.acta.build](https://docs.acta.build). Lorsqu'un détail de la skill entre en conflit avec la documentation en direct, la documentation en direct prévaut. + `, +}; diff --git a/src/content/docs/modules/mcp/fr/index.ts b/src/content/docs/modules/mcp/fr/index.ts index f040c54..d7637bc 100644 --- a/src/content/docs/modules/mcp/fr/index.ts +++ b/src/content/docs/modules/mcp/fr/index.ts @@ -1,6 +1,8 @@ import type { DocPage } from "@/@types/docs"; +import { agentSkills } from "./agent-skills"; import { mcp } from "./mcp"; export const pages: Record = { + "agent-skills": agentSkills, mcp, }; diff --git a/src/content/docs/navigation/en.ts b/src/content/docs/navigation/en.ts index 3a0e9a4..e589849 100644 --- a/src/content/docs/navigation/en.ts +++ b/src/content/docs/navigation/en.ts @@ -48,6 +48,7 @@ export const navigation: NavigationItems = { ], ia: [ { slug: "ai-overview", title: "AI Overview" }, + { slug: "agent-skills", title: "Agent Skills" }, { slug: "mcp", title: "MCP" }, { slug: "mcp-clients", title: "MCP Client Setup" }, { slug: "ai-prompts", title: "Prompt Recipes" }, diff --git a/src/content/docs/navigation/es.ts b/src/content/docs/navigation/es.ts index 99c0aad..100f32b 100644 --- a/src/content/docs/navigation/es.ts +++ b/src/content/docs/navigation/es.ts @@ -48,6 +48,7 @@ export const navigation: NavigationItems = { ], ia: [ { slug: "ai-overview", title: "Resumen de IA" }, + { slug: "agent-skills", title: "Agent Skills" }, { slug: "mcp", title: "MCP" }, { slug: "mcp-clients", title: "Configuración por Cliente" }, { slug: "ai-prompts", title: "Recetas de Prompts" }, diff --git a/src/content/docs/navigation/fr.ts b/src/content/docs/navigation/fr.ts index 445624d..8d5078d 100644 --- a/src/content/docs/navigation/fr.ts +++ b/src/content/docs/navigation/fr.ts @@ -46,7 +46,10 @@ export const navigation: NavigationItems = { { slug: "did-registry", title: "Registre et Resolver" }, { slug: "did-library", title: "Bibliothèque TypeScript" }, ], - ia: [{ slug: "mcp", title: "MCP" }], + ia: [ + { slug: "agent-skills", title: "Agent Skills" }, + { slug: "mcp", title: "MCP" }, + ], dapp: [ { slug: "dapp-overview", title: "Aperçu" }, { slug: "dapp-getting-started", title: "Premiers Pas" }, diff --git a/src/layouts/app-shell/shared.tsx b/src/layouts/app-shell/shared.tsx index 4ad2bbd..488df4e 100644 --- a/src/layouts/app-shell/shared.tsx +++ b/src/layouts/app-shell/shared.tsx @@ -39,6 +39,7 @@ import { Network, Package, Plug, + Puzzle, Rocket, ScanSearch, ScrollText, @@ -112,6 +113,7 @@ const NAV_SUB_ITEM_ICONS: Partial> = { "did-registry": Server, "did-library": Braces, "ai-overview": Sparkles, + "agent-skills": Puzzle, mcp: Cable, "mcp-clients": Plug, "ai-prompts": Lightbulb,