Connect agents

Agents see granted Ready versions by default. An author may explicitly open and test only their own current Draft; it is marked Unreviewed, remains private to that author, and never includes a trusted security report. Versions under review are not available for installation.

Every newly released Ready version is bound to a trusted package scan. See Skill security for how validation, risk gates, human review and signed installation fit together.

Direct MCP clients

Claude Code, Codex, Cursor, VS Code, Windsurf and similar tools authenticate with a workspace-bound access key sent as an X-API-Key header. One key works from any MCP client — the workspace only records which client used it last.

For Claude Code it is a single command:

claude mcp add codenskills -t http \
  --header "X-API-Key:cs_key_..." \
  https://your-endpoint/mcp

For Codex, add Codenskills to ~/.codex/config.toml:

[mcp_servers.codenskills]
url = "https://your-endpoint/mcp"
http_headers = { "X-API-Key" = "cs_key_..." }

Editors that read a JSON config use the same endpoint and header inside mcpServers:

{
  "mcpServers": {
    "codenskills": {
      "type": "http",
      "url": "https://your-endpoint/mcp",
      "headers": { "X-API-Key": "cs_key_..." }
    }
  }
}

Keys are created from Agents in the app and are scoped to skills:read plus Draft-only skills:write. See Access keys for expiry and rotation.

Hosted connectors (ChatGPT and Claude)

ChatGPT Apps and Claude Connectors authorize with OAuth instead of a key. Add the Codenskills connector in the client, approve the consent screen, and the connector is linked to your account.

Each connector is pinned to the company Workspace selected during authorization. It cannot cross into a different customer Workspace.

During consent, Codenskills shows the connector capabilities it is enabling: reading/installing granted skills, requesting access, submitting your own drafts for review, and deciding requests only where your live workspace role or reviewer assignment already allows it. Connector permissions never turn a normal member into an admin or grant access to a private skill.

Interactive views in ChatGPT and Claude

Lists and governance results open as a compact interactive Codenskills view inside the conversation. Depending on your permissions, you can:

• search and inspect Ready skills and collections;
• save a complete AI-authored package as a new skill Draft or version Draft;
• open Drafts, search your authored Drafts, inspect the package and select Test draft before scanning it;
• switch the connector's active workspace;
• request access and review your request status;
• inspect the trusted package security report;
• approve or reject access and version reviews with an audit note;
• watch a background package scan until the review is submitted; and
• download an available update as a signed ZIP through the host's download confirmation.

Lists and queues include compact navigation between related workspace sections. Skill details, security reports, scan progress, downloads and completed actions open as focused views without repeating a full app shell. Completed actions put the skill name and outcome first; request ids remain available only under technical details.

The view follows the host's light/dark theme and does not contact the internet directly. Every action goes back through the authenticated MCP connection, so the same grants, role checks, review rules and audit trail apply as in the web app.

If a company Workspace passes its billing grace period, OAuth connectors also pause privilege-increasing governance actions such as new requests, submissions and approvals. Rejecting/cancelling work and runtime read/install access to already-approved skills remain available; see Billing & seats.

For review cancellation/decisions and access decisions, the connector confirms the request id, skill slug and latest request timestamp together. If the item changed or the skill name does not match, Codenskills stops the action and asks the agent to refresh instead of changing a different request. A failed action keeps the confirmation and audit note open, with a short recovery message instead of internal validation details.

What agents can do

Through MCP, connected agents can discover the skills and collections they are allowed to see, read each skill's SKILL.md and file listing, and install approved packages. Access follows the workspace's rules: your role, group memberships and per-skill grants decide what each agent can list and pull.

Draft testing is a separate author-only path. It requires Draft write plus the connection's normal install permission and uses the version's author, not the specific key or connector, as identity. Another connection belonging to the same author can test it; another member, owner or admin cannot execute it just because of their role. Drafts are never added to collection installs or update checks.

Every authenticated MCP connection can call save_skill_draft. For example: “Create a skill for reviewing incident reports and save it to my Codenskills.” The agent sends the expanded package, and Codenskills returns a Draft receipt. Direct access-key clients may save and test the Draft but cannot scan or submit it; hosted OAuth connectors may also request access, submit the Draft for its required scan/review, and act on governance queues when authorized. Both direct keys and eligible OAuth connectors can select Test draft for that author's current Draft.

Checking for skill updates

Update checks happen from the connected client, not from the Codenskills web app. The client sends the skill versions installed on that machine, and the workspace compares them with the current Ready versions you can access.

When an update is available, the interactive view shows Download update. The next states are Preparing update package… and Update package ready, followed by Download ZIP. This creates a signed download that expires after 15 minutes; it does not replace the installed skill automatically. Your client still downloads, verifies and installs the ZIP.

Installing skills from an agent

Agents install full packages — SKILL.md plus any bundled references, scripts and assets — through a signed download:

1. The agent calls create_install_session with a skill slug (or a collection slug to install a whole collection at once).
2. The workspace returns a download link that stays valid for 15 minutes, plus a checksum_sha256 for the ZIP and suggested install locations per client.
3. The agent downloads the ZIP with a plain GET (no key needed on that link), verifies the checksum, and unzips it into its skills directory — for example ~/.claude/skills/<slug>/ for Claude Code.

Collection installs come as one ZIP with a folder per skill. Only Ready skills you have access to are included; anything skipped is listed in the response so the agent can tell you why. If a version is pulled from the workspace after the link was created, the download stops working immediately — create a new install session to pick up the current state.

To test an authored Draft, the same tool uses target: "my_draft" with a skill_slug. The result is explicitly labelled draft, author_only and unreviewed; collections are rejected. The link is also bound to the exact Draft snapshot: changing or deleting it, submitting it for review, or releasing it as Ready makes the 15-minute link return 410 Gone. Create a new session after every Draft change. A ZIP already downloaded to your machine is not remotely revoked.