Commonset for Developers

Commonset gives developers a governed way to build and reuse AI capabilities without tying the organizational workflow to one model provider.

You can work with capabilities through the application and, where enabled, through Commonset MCP.

The developer workflow is designed around a simple rule:

Experiment quickly, preserve provenance, and make broader trust explicit.

The Core Developer Model

Keep these objects separate in your mental model:

• Capability: durable organizational identity
• Version: concrete revision of the capability
• Provider mapping: relationship to a provider-specific skill or version
• Review: governance evaluation of a version
• Access: who can discover, use, review, or manage the capability
• Distribution: where an approved version has been published

Provider IDs should be treated as mappings, not as the canonical identity of the Commonset capability.

Discover Trusted Capabilities

Before building something new, search the Commonset registry.

A capability that already solves the problem may have:

• an approved version
• clear ownership
• supporting files
• a provider distribution
• established review history

Reusing a trusted capability is usually better than creating another provider-specific copy that has to be governed independently.

Work Through the Application

In the Commonset application, developers with the appropriate permissions can:

• create a capability
• create new versions
• inspect instructions and files
• see review, trust, and availability state
• run or review security analysis
• submit versions for review
• compare changes
• publish approved versions through configured provider integrations when allowed

The exact actions visible to you depend on your organization role and capability grants.

Commonset MCP

Commonset MCP exposes governed capability operations to MCP-compatible clients.

The MCP surface uses the authenticated user's existing Commonset permissions rather than creating a separate authorization universe.

This lets an AI client participate in the same registry and governance model as the web application.

Read Tools

The current MCP capability surface includes read operations such as:

• list_capabilities
• search_capabilities
• get_capability
• get_capability_file

These tools return versions that are actually available to the authenticated user.

A creator may receive a trusted creator-only draft while broader users receive only versions allowed by Commonset trust and access rules.

Workflow and Status Tools

Developer workflow tools can expose information such as:

• capabilities you own or can manage
• registration state
• review state
• trust/security result
• runtime availability
• provider-publication gate readiness

This is useful because latest version and runtime version are not always the same thing.

A newer draft can exist while an older approved version remains the version other users can consume.

Create a Capability Draft Through MCP

Where enabled, create_capability_draft can save a new private capability draft owned by the authenticated user.

The draft goes through the same core Commonset pipeline for:

• validation
• security analysis
• provenance recording
• encrypted storage

If the applicable automated trust checks pass, the draft can remain available to its creator according to policy.

The tool does not automatically:

• submit the version for review
• approve it
• publish it to a provider

Creator availability is intentionally not organizational approval.

Create a New Version Draft

create_capability_version_draft creates a new draft revision of an existing capability you can manage.

The workflow can inherit unchanged material from the current base and add or replace supplied text files.

When using automation, provide the expected base version when possible. This acts as stale-write protection and reduces the chance of building from a version that changed while your client was working.

A new version is the correct place to change previously approved behavior.

Security Audit Tools

MCP can expose the recorded security audit for a version and, with sufficient permission, re-run Commonset's existing security analysis.

Useful operations include:

• reading the latest audit without changing state
• re-running analysis after a draft changes

A security audit can affect trust and availability, but it never approves or publishes a capability by itself.

Submit for Review

Where enabled, the MCP workflow can submit a manageable version for review.

Submission creates a review workflow; it does not approve the version.

Approval remains a governed human decision in Commonset rather than an autonomous MCP write operation.

This boundary is intentional: AI clients can help create and prepare capabilities without becoming the authority that declares them organizationally trusted.

Working With Supporting Files

Capabilities can include supporting files referenced by their instructions.

When consuming a capability through MCP:

1. Read the capability instructions.
2. Inspect the supporting-file manifest.
3. Request only the file paths needed for the current task.

When creating drafts, keep supporting files focused and explain their role. Executable resources deserve extra reviewer attention because their security impact can be larger than a plain reference document.

Version and Content Integrity

Commonset records hashes for versions and files so revisions have stable integrity identifiers.

Approved versions are immutable in the application model. Changing approved content means creating another version.

For developers, this provides a dependable contract:

the version you reviewed is not supposed to mutate into different behavior later.

Provider Integrations

Provider publishing is separate from capability creation.

A provider adapter may support:

• discovery
• metadata
• version history
• source import
• publication
• a particular audience model

Do not assume that because two providers both use the word “skill,” their APIs or distribution semantics are identical.

Commonset keeps provider-specific IDs and versions attached to the provider mapping while maintaining its own stable capability/version identities.

Handling Provider Drift

A linked provider record may show:

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

If a provider version changes outside Commonset, treat it as an input to reconcile rather than overwriting the local approved version automatically.

Import the remote source when supported, compare it, and send it through review.

Recommended Developer Workflow

For a new capability:

1. Search Commonset before creating a duplicate.
2. Create a draft in the app or through MCP.
3. Keep the capability provider-neutral where practical.
4. Add only necessary supporting files and tools.
5. Review trust/security results.
6. Iterate privately while creator-only availability is allowed.
7. Create clear release notes.
8. Submit the version for review.
9. Respond to reviewer feedback.
10. Publish only after the version is approved and provider-specific checks pass.

For an existing approved capability, begin at step 2 by creating a new version, not by modifying the approved one.

Design for Portability

When writing reusable capability instructions:

• separate durable business intent from provider-specific mechanics
• keep provider extensions explicit
• document required tools and assumptions
• avoid unnecessary model-specific language
• preserve supporting reference material with the version

The more clearly the durable capability is separated from provider details, the easier it is to reuse, review, and move across AI platforms.