Create and export a managed Skill¶

Generate a managed Skill when reviewed evidence can support reusable instructions and validation checks. Approval creates an immutable Skill Revision. A separate export makes one exact Revision available to Codex.

Before you begin¶

Start the Server with a generation model and confirm that managed Skill generation is enabled:

export POWERCONTEXT_SERVER_INFERENCE_GENERATION_MODEL=provider:model-name
powercontext server run

In another terminal:

powercontext capabilities

The output should report Managed Skill generation: enabled. Choose one provenance origin before generating:

1. Generate a Candidate¶

From an approved Experience:

powercontext skill generate \
  --scope-id project:example \
  --origin experience \
  --artifact-ref experience/EXPERIENCE_ID@REVISION \
  --reason "Turn the reviewed lesson into reusable instructions."

From exact Sources instead:

powercontext skill generate \
  --scope-id project:example \
  --origin source \
  --source-ref content/SOURCE_ID \
  --reason "Create a Skill from the approved operating procedure."

The response has either status: pending with a Candidate or status: no_op with no Candidate. Generation does not approve, install, export, or execute the proposal.

2. Review and approve the Candidate¶

Inspect the returned Candidate:

powercontext candidate show --scope-id project:example CANDIDATE_ID

Check its name, discovery description, complete instructions, validation checks, and exact lineage. Then approve the version you inspected:

powercontext candidate approve \
  --scope-id project:example \
  --expected-version 1 \
  CANDIDATE_ID

The response should have status: approved and an exact Skill result_artifact. Approval does not install the Skill or grant execution authority. To revise or reject the proposal, follow Review Candidates.

3. Read the exact Skill Revision¶

Use the Artifact ID and Revision from result_artifact:

powercontext skill show \
  --scope-id project:example \
  --revision 1 \
  SKILL_ID

The response contains the approved content and its exact Source and Artifact lineage. Managed Skills do not enter PreparedContext; they remain available through exact reads and explicit export.

4. Export the Revision to Codex¶

For Codex export, the Skill name must contain at most 64 lowercase letters, digits, and single hyphens. Its description must contain at most 1,024 characters and no angle brackets. The destination directory name must match the Skill name. For a repository-local Codex Skill:

powercontext skill export \
  --target codex \
  --scope-id project:example \
  --revision 1 \
  --destination .agents/skills/backend-validation \
  SKILL_ID

The command creates a new directory containing:

.agents/skills/backend-validation/
├── SKILL.md
└── powercontext.json

powercontext.json records the exact Artifact reference and rendered-content hash. The command refuses to replace an existing destination. The managed Skill Revision remains authoritative; the directory is a host-local projection.

Codex detects the exported repository-local Skill automatically. If it does not appear, restart Codex.

Evolve a Skill from usage¶

Use the usage origin with the exact current Skill Revision and Sources that record how it performed:

powercontext skill generate \
  --scope-id project:example \
  --origin usage \
  --target skill/SKILL_ID@REVISION \
  --source-ref content/USAGE_SOURCE_ID \
  --reason "Update the validation steps from observed usage."

The CLI adds the target to Artifact evidence. Review and approve the replacement Candidate before exporting its new Revision. If an export destination already exists, inspect and handle that projection explicitly before exporting again; the command never overwrites it.

For external Agent-native Skill discovery and import contracts, see Interfaces.