Connecting AI Providers

Provider integrations let Commonset discover, import, compare, and distribute provider-specific AI capabilities while keeping Commonset's organizational model independent from any one vendor.

A connection is not just a provider name. It represents a specific provider surface with its own API behavior, credential scope, audience model, and supported operations.

Who Should Connect Providers

Provider connections are organization-level configuration and should generally be managed by organization owners or administrators.

The person connecting a provider should understand:

• which provider account, workspace, or project the credential belongs to
• what the credential can read or write
• who can access capabilities published through that provider surface
• how credential rotation or revocation will be handled

Current Provider Surfaces

Commonset's integration model can support multiple surfaces independently.

Current product work includes surfaces such as:

• Claude API Skills
• OpenAI API Skills

Additional provider or workspace surfaces can be added through provider adapters without changing the core Commonset capability model.

The available options in your organization may depend on enabled features and provider support.

1. Open Integrations

From the organization administration area, open Integrations.

Each provider card represents a particular provider surface rather than a generic promise that every provider supports the same behavior.

2. Add the Provider Credential

Enter the credential required by that provider surface.

Commonset stores connected provider credentials in encrypted form and retains only a limited credential hint for display.

Treat the provider credential as a privileged machine identity:

• use the narrowest permissions that support the intended workflow
• avoid sharing one human user's broad credential when a scoped service credential is available
• rotate credentials according to your organization's policy
• revoke the credential if the integration is no longer needed

Claude API Skills credential baseline

For Claude API Skills, prefer a dedicated service account scoped to the single workspace Commonset should govern. The validated least-privilege baseline is organization role Developer plus Workspace Developer on that workspace. Workspace Admin is broader than Commonset needs for normal skill inventory/import/publish workflows. Avoid Restricted/Limited Developer when source import is required because that role cannot download files.

3. Validate the Connection

After connection, Commonset can test what the provider surface actually supports.

Provider capabilities may include:

• discovery
• metadata retrieval
• version history
• source pull/import
• publication
• distribution or audience controls

A provider can support one operation and not another. Commonset records these capabilities separately so the UI can explain what is possible instead of failing later without context.

4. Understand the Connection Scope

Before syncing, confirm the scope represented by the credential.

Examples include:

• a provider workspace
• an API project
• another provider-defined administrative boundary

The inventory Commonset can discover is limited to what the provider API and credential expose.

Connecting a project-scoped credential does not make Commonset omniscient across the provider's entire organization.

5. Sync Provider Inventory

Use the provider sync action to read visible provider records into Commonset's inventory.

The inventory can help identify:

• newly discovered provider skills
• previously cataloged records
• provider records that changed
• records that are no longer visible

Inventory records remain distinct from imported Commonset source. A provider may expose metadata and version history without exposing downloadable source content.

6. Import or Catalog Provider Skills

After sync, review the provider inventory and decide which records should become governed Commonset capabilities.

When source import is supported, Commonset can preserve the provider's identity and version information as provenance while creating a local version.

When only metadata is available, Commonset can still catalog the provider record without pretending it has source content it cannot retrieve.

For Claude API Skills, custom workspace skills now support this full source-import path with the validated Developer / Workspace Developer service-account setup. Provider-managed, example, and plugin skills remain read-only metadata records unless Anthropic exposes a supported source path for those asset types.

7. Publish Approved Versions

When the provider supports publication, Commonset can push an approved version back to the connected surface.

Publication should require two layers of checks:

Commonset gate

The version is organizationally approved and passes the current trust requirements.

Provider gate

The connection supports publication, provider-specific validation passes, and the provider audience is compatible with Commonset access policy.

This keeps provider mechanics from silently overriding organizational governance.

Provider Audience Differences

Provider audience scope is one of the most important integration details.

A provider may make a published capability available to an entire workspace or project even when Commonset access is narrower.

Commonset should surface that difference explicitly.

For example, the current Claude API Skills integration can represent workspace-scoped distribution where per-skill user or group ACLs are not available through that surface. A narrowly granted Commonset capability may therefore require a distribution policy decision before publication.

Other provider surfaces may use project-level or different audience boundaries.

Connection Status

A provider connection can be:

• Connected
• Error
• Disabled

An error does not change the identity or approval state of Commonset capabilities. It means provider operations may not be available until the connection is healthy again.

Keep local governance state separate from provider connectivity.

Provider Activity and Sync State

Commonset records provider activity so administrators can understand what happened across the connection.

For linked capabilities, useful states include:

• Linked
• Imported
• In sync
• Local ahead
• Remote changed
• Conflict

These states describe synchronization, not trust.

A provider copy can be in sync with a Commonset version that later becomes deprecated, or a remote change can create a conflict without changing the approval history of the local version.

Credential Hygiene

Recommended practices include:

1. Use the least-privileged provider credential available.
2. Document which workspace or project it represents.
3. Rotate it when staff or provider policy changes.
4. Review provider activity after connection changes.
5. Disable or revoke unused connections.
6. Treat provider audience scope as part of the security review.

The Integration Principle

Commonset should not make every provider look identical.

Instead, it provides a stable organizational layer above them:

Commonset owns the capability identity, governance, access, and history. Provider adapters translate that trusted state into the operations each provider actually supports.