Creating and Publishing a Capability

Commonset separates creating a capability from publishing it to an AI provider.

That separation is intentional.

Creation is where you define and iterate on the organizational capability. Publishing is a controlled distribution action that happens only after the applicable review, trust, access, and provider checks are satisfied.

Start With the Organizational Purpose

Before choosing a provider format, define what the capability is meant to accomplish.

Good capability descriptions answer:

• What job should this capability perform?
• Who is it for?
• What inputs or tools does it expect?
• What important boundaries should it follow?
• Who owns its ongoing accuracy?

This keeps the capability understandable even if its provider-specific representation changes later.

1. Create the Capability Record

Create a new capability in Commonset and provide a clear name, description, and owner.

The capability record is the durable organizational identity. Individual versions and provider mappings attach to that identity over time.

Use a name that describes the work rather than the vendor. Prefer Contract Review over Claude Contract Review unless the capability is intentionally provider-specific.

2. Create the First Version

The capability's behavior belongs in a version.

A version can include:

• instructions
• provider-compatible frontmatter or metadata
• reference material
• supporting files
• scripts or other resources
• release notes

Commonset records a content hash so the version can be identified and compared reliably.

Choose a version label that your team can understand. A semantic versioning convention such as 0.1.0, 1.0.0, and 1.1.0 works well, although the important Commonset rule is that version identities remain unique within the capability.

3. Validate the Package

Before broader use, Commonset validates the capability structure and content it can evaluate.

Validation can identify problems such as malformed package structure or unsupported content before the capability enters review or provider publication.

When executable or higher-risk resources are present, reviewers should understand what those resources do rather than treating the package as instructions alone.

4. Run Security and Trust Analysis

Commonset records a security/trust result for each version.

Working results include:

• Pending
• Clean
• Warning
• Blocked
• Error

A Clean result means the automated checks did not find a condition that currently blocks trust. It does not mean the capability has been organizationally approved.

A Warning can require reviewer attention or explicit risk acceptance. A Blocked result prevents the version from passing the trust gate until the blocking condition is resolved.

5. Use Creator-Only Iteration Where Allowed

Commonset is designed to avoid forcing creators into an all-or-nothing choice between experimentation and governance.

When a draft passes the applicable automated trust checks, your organization's policy may allow the creator or capability owner to continue using that version privately while formal governance continues.

Creator-only availability is deliberately narrower than approval:

Creator available does not mean organization approved.

The version cannot be treated as generally trusted or published to a provider merely because its creator can use it.

6. Request Review

When the version is ready for broader trust, submit it for review.

Reviewers can evaluate:

• release notes
• changes from the previous version
• security findings
• capability footprint or tool changes
• provenance
• ownership
• intended audience
• provider distribution implications

Commonset may also provide an AI-assisted explanation of changes when an appropriate LLM integration is configured. That explanation is advisory; deterministic changes, security checks, and human review remain authoritative.

7. Approve the Specific Version

Approval is version-specific.

If v1.0 is approved and you later change the instructions or files, the new content belongs in a new version and must earn its own approval.

Approved versions are immutable in the current Commonset model. Their content and files cannot be silently altered after the governance decision.

That makes the approval meaningful: reviewers know exactly what content they approved.

8. Confirm Access

Approval answers Can we trust this version?

Access answers Who can use it?

Before distribution, confirm that the intended Commonset audience is correct.

Access can be granted at organizational, group/team, or individual-user scope, depending on your configuration and permission model.

A capability can be approved without being available to the entire organization.

9. Check Provider Distribution Scope

Provider publication has its own constraints.

A provider surface may publish to a workspace, project, or other audience that does not exactly match Commonset's access model.

Before Commonset publishes a version, it can evaluate whether the provider audience is compatible with the capability's Commonset grants and organizational policy.

This matters especially when a provider lacks per-skill user or group controls. A technically successful publication should not accidentally make a narrowly governed capability available to a broader provider audience.

10. Publish the Approved Version

Once the Commonset gate and provider-specific checks pass, publish the approved version through the connected integration.

Commonset records the relationship between:

• the local capability
• the local approved version
• the provider skill or record ID
• the provider version
• the most recent push or pull state

The provider executes or stores its representation of the capability. Commonset remains the organizational governance layer.

After Publication

Publishing is not the end of the lifecycle.

Commonset can track whether the local and provider states remain aligned.

You may see conditions such as:

• in sync
• local ahead
• remote changed
• conflict

If the provider copy changes independently, bring the change back through the import and review workflow instead of silently replacing the approved Commonset version.

Updating an Existing Capability

To change an approved capability:

1. Create a new draft version.
2. Describe the change in release notes.
3. Run validation and trust analysis.
4. Compare it with the currently approved version.
5. Request review.
6. Approve the new version if appropriate.
7. Confirm access and provider audience.
8. Publish the new approved version.

This preserves the history of what changed, what was trusted, and what was actually distributed.

A Useful Rule

Think of the lifecycle as two separate gates:

Commonset gate: Is this exact version approved and currently trusted for the intended audience?

Provider gate: Can this exact version be distributed safely through this provider surface?

Both need to pass before provider publication.