remek governs itself
Its own governed records include policy, provenance, positive and contrastive cases, the retained design brief, and evidence receipts naming the host and version.
Governed source and release layer for Agent Skills
Your skills are an asset. Govern them like one.
Build a private library of skills you can trust and selectively share. Keep each skill’s provenance and evidence tied to exact bytes, review every change, and control what ships.
See remek in practice: browse public Agent Skills →
Python 3.11+ · standard library only offline by defaultmacOS & native LinuxMIT
The governance gap
Can you answer these questions about every skill you ship?
A folder and a Git commit are useful, but they do not answer the release questions on their own.
- What exact skill bytes are we talking about?
- What changed since the last accepted release?
- Which results apply to those exact bytes?
- Are those results still current—or stale?
- Who declared approval for this release?
- Is this for a private audience or the public?
- Does the committed mirror still match the approved source?
How it works
Know the source. Review the change. Control what ships.
Start from a known source
Your agent writes the confirmed procedure to a file you review. remek starts an owner-only workspace from that file, a design brief, or a reviewed Agent Skill—not the chat—and records its origin.
Review the actual change
Before changing a skill or release repository, remek saves an exact plan and rebuilds the real diff for you. If the current state no longer matches the plan, remek refuses to apply it.
Record evidence and approval
Hosts, test suites, and external evaluators run outside remek. Evidence binds the exact candidate and evaluation setup; approval binds the candidate, provenance, distribution, and target. Change a bound input and the affected record no longer counts for release.
Release only selected skills
remek prepares only the selected skill files and release-manifest.json for the chosen private or public repository. You control visibility, commit, and push; remek does none of them.
Who is it for?
Private skill owners, client work, and platform teams
Private skill owners
Keep personal and business skills in one private Git repository, with provenance and evidence tied to exact versions.
Client work
Give each client a separate allowlist and private target. Screen declared names, hostnames, and codenames; bind private release context by digest instead of exporting it.
Platform teams
Set one governance standard across team skills: provenance, exact change plans, version-bound evidence, and pre-push verification.
Review the exact change before it lands
See the exact diff before the skill changes
scaffold starts an owner-only workspace from one completed-work file, design brief, or reviewed Agent Skill. For captured work, it copies only the file your agent shows you.
accept saves a plan; plan show reconstructs the current diff. apply changes governed source only while that plan still matches—otherwise it refuses and you create a new plan.
after verifying a flaky-deploy fix
YOU
AGENT
./remek scaffold --name deploy-safely --origin captured --source /work/deploy-safely.md …
scaffold: disposable workspace created
AGENT
./remek accept --workspace /work/deploy-safely --output /tmp/accept.json
accept: exact plan saved; review it with plan show before apply
./remek plan show /tmp/accept.json
AGENT
YOU
./remek apply /tmp/accept.json
AGENT
later: candidate edited after the plan was saved
./remek apply /tmp/accept.json
apply: plan differs at plan.bindings.candidate; nothing applied; recreate and review
ERROR plan.stale: plan differs at plan.bindings.candidate; nothing applied; recreate and review
what you saw is what landed—or drift left everything untouched.
agent prepares
remek saves the exact plan
you review
apply lands only that plan
Skill lifecycle
From owned work to reviewed release files
- Author Your agent works in an owner-only workspace from one completed-work file, one design brief, or one reviewed Agent Skill.
- Accept remek saves an exact plan; you inspect the reconstructed diff before apply.
- Record evidence You record observations from a named host, test suite, or external evaluator. remek runs none of them.
- Approve The approval records the exact candidate, provenance, distribution, target, exceptions, reviewer, and date. It does not grant access.
- Release Prepare the selected skill payload and manifest, then verify the committed mirror before a separate push.
Inspectable proof
Trust artifacts you can read yourself
Small enough to actually review
The Python 3.11+ core is standard-library only. CI enforces ceilings of 125,000 tracked tokens, 70 files, 250 collected tests, one schema family, and zero third-party runtime dependencies.
A real byte-bound evidence record
This abridged receipt is from remek’s own governed source. The candidate digest, evaluator profile, and per-case pass counts travel together; changing a bound input makes the proof stale.
View abridged remek.1 receipt
{
"kind": "eval-receipt",
"skill": "remek",
"candidate": "9f90410140f6360c0fa9e09b2045a96b3e9238e5e1666db37d1f1d4acd036966",
"evidenceKind": "behavior",
"profile": {
"name": "Codex desktop gpt-5.6-sol ultra",
"version": "gpt-5.6-sol / Codex 26.715.31925+5551"
},
"results": [
{ "caseId": "release-refusal", "passCount": 3 },
{ "caseId": "audit", "passCount": 3 }
]
}
Inspect a real released mirror
agent-skills is a public catalog projection prepared with remek. Its manifest binds the materialized skill payload without exposing private source or governance records.
Browse the catalog →
Inspect its manifest →
python3 tools/verify_release_manifest.py /path/to/mirror
Audit any skill before you install it
Point remek at a skill folder for read-only findings and repair hints. No governed repository is required; candidate content is never executed.
python3 -I -S -B \ /path/to/remek/scripts/cli.py \ audit /path/to/skill
Quick start
Start with your coding agent
Install
gh --version REMEK_VERSION="$(gh release view --repo benblackthorn/remek --json tagName --jq .tagName)" gh skill preview benblackthorn/remek "remek@$REMEK_VERSION" gh skill install benblackthorn/remek remek --pin "$REMEK_VERSION" --agent codex --scope user python3 -I -S -B "$HOME/.codex/skills/remek/scripts/cli.py" --version
Requires GitHub CLI 2.90+. The release query resolves the latest published tag once; preview and install reuse that exact value. The final command should match $REMEK_VERSION without its leading v. For Claude Code, use --agent claude-code and verify under $HOME/.claude/skills/. npx skills is a public alternative but has no complete private-repository contract.
Initialize
Tell your agent: "Set up my private governed skills source with remek. Discover my existing conventions and repositories first, then confirm the name and absolute path before creating anything."
remek never creates, commits, or pushes the repository.
Capture your first skill
Tell your agent: "Capture this as a skill with remek."
Your agent writes the confirmed procedure to one file and shows you the accept plan before applying it. remek captures that file—not the chat or neighboring source files.
FAQ
Common questions
What does remek do?
remek ties each skill’s provenance, planned changes, evidence, approval, and release files to exact versions. Your agent authors the skill; Git commits and pushes; installers place consumer copies.
How is remek different from gh skill and npx skills?
gh skill and npx skills install consumer copies for coding agents. remek governs the source before installation: provenance, exact plans, evidence, approvals, release contents, and pre-push verification. Git still owns commits and pushes.
Does remek replace tools that write skills?
No. remek is delivered as an Agent Skill so your coding agent can operate it, but its job is governance. Your agent—or a separate authoring workflow you choose—writes inside the owner-only workspace from completed work, a design, or a reviewed import. remek does not invoke or certify any authoring tool.
What can a skill start from?
remek does not read or save a chat. Captured work uses one existing file; a design uses one brief; an import uses one reviewed compatible Agent Skill. Captured and designed inputs are copied exactly into .remek/skills/<name>/sources/. An import records its upstream repository, ref, and candidate identity.
Can I bring an existing Agent Skill into remek?
Yes, as a reviewed compatible import. remek snapshots the candidate, strips only recognized installer metadata, and requires upstream identity, policy, and cases before acceptance, plus complete rights information before release. It does not automatically convert arbitrary files or claim their provenance.
Can remek improve a skill I already have?
Your agent can revise a governed skill; remek does not decide whether the revision is better. You review an exact plan before it lands. Changing the candidate returns the skill to draft and clears its previous evidence and approvals. If the governed source changed while the revision was prepared, remek refuses.
Who designs and runs skill evaluations?
Your authoring workflow defines the cases and graders; external sessions, test suites, or evaluators run them. remek records their declared setup and results, detects staleness, and cannot prove an evaluator was honest.
Can remek govern skills inside an existing project?
Yes. Project mode governs an exact selected set under .agents/skills/ and leaves installer-managed or otherwise foreign neighbors alone. Existing project skills still require an explicit reviewed import before remek owns them. Managed release integrity checks inherit the enclosing repository’s full Git object-database cost under a 30-second bound; a very large monorepo may need a dedicated governed source.
Which coding agents can I use, and do I need the terminal?
remek uses the Agent Skills format and also has a plain CLI. After installation, ask in plain language; your coding agent can run the CLI and explain each plan. An installer's host list shows placement, not identical routing or behavior. The recorded routing evidence is host- and version-specific; verify the host and version you intend to use.
Are remek digests signatures?
No. SHA-256 digests identify exact bytes and bound context; they are not signatures and remek holds no signing keys. If your organization requires signing, create an externally governed signed commit—or sign a tag pointing to the verified commit—before release verify. Signing replaces neither current evidence nor release approval.
Where do my skills live? Does remek upload anything?
In repositories you own. remek has no account or telemetry and never uploads skill payload or pushes. Ordinary workflows are offline. Release workflows use bounded local Git checks and an authenticated GitHub CLI query for the exact target identity and visibility.
How are private and public releases separated?
Every skill starts source-only. Each distribution is an exact private or public allowlist with its own target and evidence policy. Public release also requires public eligibility, complete rights, current evidence and approval, blocked private disclosure, and a separate public repository and history. remek-managed mirror content is limited to selected skills and release-manifest.json; .remek/ stays in the source. Screening is defense in depth; approval is not access control.
Can I use remek for client work under NDA?
Yes. Give each client a separate distribution allowlist and private target. With private disclosure set to block, remek flags declared names, hostnames, and codenames; detected credential-shaped content cannot be excepted. Manifests digest private release context instead of exporting it, while retaining the opaque source commit for lineage. remek never copies the source’s .remek/ tree into a mirror.
Can it break or overwrite my skills?
Only scaffold directly creates a new owner-only workspace. Governed-source and mirror changes use saved plans that refuse drift; handled failures roll back or name residue. Guarantees cover macOS or native Linux on cooperative local POSIX storage—not Windows, WSL, network filesystems, crashes, power loss, or other writers.
What will remek never do?
It never calls a model or evaluator, executes candidate content or scripts, writes host skill directories, creates repositories, commits, pushes, tags, publishes, changes visibility, controls access, or updates consumer copies. Your skills remain plain folders in repositories you own.