Experience and Skill

Completed work often yields two reusable things. One is judgment for a similar situation. The other is a repeatable procedure an agent can follow. PowerContext stores the first as and the second as managed . Neither may move directly from model output to an approved Artifact. The distinction changes the review question. For Experience, ask whether the lesson follows from the cited outcome and will help in a similar situation. For Skill, inspect whether another agent can execute the procedure safely, including its checks and permission boundary.

Experience and Skill solve different problems

Experience keeps judgment

Experience has four parts.

situation
→ action
→ outcome
→ lesson

This is the same OpenAPI example.

Situation: the public OpenAPI contract changed
Action: regenerate and inspect the checked-in client before tests
Outcome: the generated transport matched the contract
Lesson: inspect generated drift before running contract tests

It helps later requests reason about a similar situation. The approved current Experience head may enter PreparedContext as cited evidence.

Skill keeps operating instructions

A managed Skill contains a name, a description used by the host for discovery, instructions, and validation checks. Skill is not ordinary Memory. It never enters PreparedContext and does not appear in an agent’s Skill directory merely because Review approved it.

The shared Candidate lifecycle

Both objects start as a proposal and wait for Review. A enters first. Revise a proposal with version. Approval creates an Artifact Revision.

Candidates pass Review first. Revise with version. Approval creates an Artifact Revision.

A Candidate has its own lifecycle. pending can be inspected, revised, approved, or rejected. approved is terminal and must include a result_artifact. rejected is also terminal. It must include a reason and creates no result Artifact. Every Candidate cites at least one exact Source or Artifact as evidence. The current combined limit is 32 Source and Artifact references.

Propose and generate

A proposal can come from you, or a model can draft it from bounded evidence.

Typed propose

When the content is already known, submit a structured proposal. The common operations are propose_experience and propose_skill. No generation model is required. The result is still a pending Candidate.

Model-backed generate

A model can draft a Candidate from bounded evidence. The common operations are generate_experience and generate_skill. Generation may return a pending Candidate or an explicit no-op. Without a generation provider, the operation fails before persisting a Candidate. A well-formed model response is never automatic approval.

Candidate version is not Artifact Revision

Each revise operation creates another proposal version. A Review write supplies expected_version, which binds the decision to the version that the reviewer inspected. If one reviewer reads v1 and another revises it to v2 first, the older approve call conflicts.

approve(expected_version=1) → conflict

Read v2, compare the complete proposal, then approve or reject. Do not increment the expected version mechanically. Revision is a full replacement, not a patch. Each proposal version remains independently auditable.

Approval is transactional

Approve runs one database transaction. It locks the pending Candidate, validates expected_version and lineage, then creates or revises the Artifact. For Experience it also updates the approved-head search projection. Finally it marks the Candidate approved and records the exact result_artifact. If the Candidate status update fails, the Artifact commit rolls back too. PowerContext does not leave an Artifact committed while its Candidate remains pending. Reject creates no Artifact. It records the terminal decision and reason.

“Human Review” is a product governance contract, not identity attestation. The Server cannot prove that an API caller is biologically human. Authentication, host permissions, and operating process still decide who may call approve or reject.

How Experience reaches recall

An Experience can enter PreparedContext only when all of these are true. The Candidate is approved. It is the current head of its Experience artifact. It uses the same Scope as the request. Search and the PreparedContext builder treat it as relevant. Pending, rejected, and historical Experience Revisions do not enter automatic recall. After approval of a replacement Experience, the old Revision remains available by exact read, but default recall uses the new head.

Skill provenance

Model-backed Skill generation supports three origins.

origin	Direct evidence
`experience`	One or more approved Experience Revisions, optionally with Sources
`source`	One or more exact Sources. `artifact_refs` must be empty
`usage`	An exact target Skill Revision and at least one Source. The reviewer verifies whether it truly records use

Approval of a new managed Skill applies an additional lineage rule. Artifact evidence should be Experience, not another Skill. A Skill replacement includes the target Skill and at least one bounded Source. The Server validates reference shape, not whether the Source text proves useful real-world usage. That judgment remains with the reviewer. A model cannot read only the old Skill text and promote a self-written next version.

Approval, export, and execution

Keep these operations separate.

approve Candidate
→ managed Skill Artifact Revision
→ explicit export or managed publish
→ host-local projection
→ host/user decides whether to execute

Approval

Approval creates an exact Skill Revision, for example skill/SKILL_ID@1. Nothing changes in the host filesystem yet.

Export

The CLI reads an exact approved Revision and produces a host-local package.

SKILL.md
powercontext.json

powercontext.json stores the agent kind, exact ArtifactRef, and SHA-256 of rendered SKILL.md. The managed Artifact remains authoritative. The directory is a rebuildable copy. The current CLI export targets are codex and claude_code. Do not infer managed Skill export support for Hermes, OpenClaw, DSH, OpenCode, or Pi.

Execution

PowerContext does not execute the exported Skill or grant tool permissions. The host decides when to discover it, while the user or host policy decides whether its operations may run.

Two publication surfaces

Direct CLI export is create-only. It refuses an existing destination. Server-managed safe publish is a separate surface. It creates or updates only when the projection is still PowerContext-managed, has not drifted, and is unpublished or update_available. Common projection states include unpublished, current, update_available, conflict, drifted, and incompatible. A foreign directory, local edits, multiple projections for one Artifact, or a newer published Revision cannot be silently overwritten.

Managed, external, and bundled Skills

These names refer to different objects.

Type	Authority	How it reaches the host
managed Skill	An approved PowerContext Artifact Revision	Explicit export or managed publish
external Skill	A host filesystem or registry package	Scan, resolve, then import or fork into the Candidate lifecycle
bundled Skill	Static Skill shipped with an integration plugin	Installed by host setup

A bundled project-context Skill in an OpenCode, Pi, Codex, or Claude Code integration does not imply managed Skill export support. Those features are unrelated. External Skill import or fork also does not create an approved Artifact. It creates a managed Candidate for Review, and arbitrary package scripts or assets do not execute as a side effect.

Complete the OpenAPI example

1. Prepare evidence

Capture the contract-test result as a Source and keep the exact SourceRef.

2. Experience Candidate

Propose or generate this judgment.

Situation: OpenAPI contract changed
Action: regenerate and inspect the client, then run contract tests
Outcome: generated transport matched the contract
Lesson: inspect generated drift before tests

3. Review

Read Candidate v1 and revise the lesson to produce v2. An intentional approve(expected_version=1) should conflict. Read v2 again, then approve it to get experience/EXPERIENCE_ID@1. A later relevant prepare_context may now recall the approved Experience.

4. Skill Candidate

Use the Experience Revision as origin and generate.

name: powercontext-openapi-change
validation:
  - api generation check passes
  - contract tests pass

Approval produces skill/SKILL_ID@1. PreparedContext still does not contain it. That is the expected result.

5. Export

Export exact @1 to each supported host directory. Inspect the SKILL.md content and confirm that powercontext.json refers to the same exact ArtifactRef. Edit SKILL.md manually and inspect again. The projection should become drifted, and safe publish must refuse to overwrite it.

Common failures

Generation succeeded, but the Review Inbox is empty

The operation may have returned no-op. Inspect the response instead of assuming every generation creates a Candidate.

An approved Experience is not recalled

Check Scope, current-head status, query relevance, and the PreparedContext byte budget.

The Skill is approved, but the agent cannot see it

Approval does not export. Confirm that the exact Revision was exported into a directory the current host scans.

Export reports that the destination exists

Direct CLI export does not overwrite. Inspect whether the directory is foreign, managed-current, update-available, or drifted before keeping it, selecting another path, or using controlled managed publish.

A replacement Candidate keeps conflicting

The target Skill head may have advanced. Read the current target and Candidate again rather than changing expected versions blindly.

How you know the layers are separate

Candidate version and Artifact Revision are different numbers.
Propose and generate stop at pending or no-op.
Approve and reject bind the inspected expected_version.
Experience recall uses only the approved current head.
Skill remains outside PreparedContext.
Approval, export, and execution stay three steps.
Codex and Claude Code are the only current export targets listed.
Local drift and conflict prevent overwrite.

The mental model is now complete. Continue with Install and run the Server and exercise these objects with real IDs, Citations, and Revisions.

Start a local Server

Write a Memory, find it, then get a cited PreparedContext.

Finish one Review

Submit a Candidate from exact evidence, check the version, then approve or reject.

Core ideas