| name | manage-tink |
| description | Tink CLI for repository-owned Agent Skills. Use when the user asks to initialize Tink; inspect GitHub skill sources; add, list, check, lock, verify, sync, refresh, or remove project skills; manage grouped skillsets; use the home library or catalog; harvest harness skills; configure shell completion; update Tink; refresh embedded manage-tink; or destroy project agent scaffolding. |
Manage Tink
Live skills and skillsets live only under the project's .agents/skills/.
The project is authoritative; the home library conforms to it. Tink's
refusals are hard stops — honor them; do not work around them.
When to Use
Use this workflow only for the Tink request that triggered the skill. Do not
broaden inspection authority into mutation authority.
Inputs
- The current project root.
- The user's requested Tink operation and its explicit mutation authority.
- Any supplied skill source, skill name, or canonical
NAME-skillset name.
Procedure
Step 1: Inspect the Requested State
If tink is missing, report the installation command and stop:
curl -fsSL https://raw.githubusercontent.com/jon-devlapaz/tink/main/install.sh | sh.
Otherwise, run only the read command matching the request:
- Project state or names:
tink skill check or tink skill list.
- Catalog or library:
tink skill list --catalog or tink library list
(tink skill list --library remains a compatibility alias).
- Project or library skillsets:
tink skillset list or
tink skillset list --library.
- Public GitHub structure:
tink inspect GITHUB_URL.
Expected: The command's exit status and output are known without writes.
On failure: Report the exact refusal or error and stop. Do not hand-parse
~/.tink/catalog or ~/.tink/skills as a substitute for a failing CLI.
Step 2: Select One Authorized Mutation
For an explicit mutation request, load
references/commands.md and select one primary
command. Do not invent flags, merge operations, force-overwrite, use private
registries, or substitute symlinks or manual copies.
Require canonical skillset names ending in -skillset; never append or remove
the suffix. skillset add reads
$TINK_HOME/catalog/by-skillset/NAME-skillset/meta.json; inspection does not
create that definition. Tink has no definition-writer command. Only when the user
explicitly authorizes creating or changing a pinned skillset definition, author
that exact external-input file using the schema in references/commands.md.
Definition authoring does not authorize installing it or editing receipts,
installed trees, or the derived by-project index.
Expected: One primary command exactly matches the user's authority.
On failure: If the request does not authorize the required mutation or a
canonical name is missing, stop and ask for the missing authority or name.
Step 3: Execute the Primary Mutation
Execute the selected mutation once. For explicitly authorized external definition
authoring, write only the exact catalog/by-skillset/NAME-skillset/meta.json
input and stop unless installation was separately authorized. Honor create-only
and divergence refusals. Use
tink skill add NAME to promote a bare library skill. Receipt-backed roots
remain skillsets. Use tink skill harvest to fill the library from known
harness roots, and only the matching tink skillset add, refresh, or
remove command for a skillset mutation.
Expected: The command finishes and its stdout, stderr, and exit status are
known.
On failure: Stop and report the failure. Do not repair Tink-managed state
by hand. Init, add, skillset refresh, and embedded-skill refresh can fail after an
earlier project, library, catalog, or guidance write succeeded. Report each
surface known or possibly changed; do not describe the failure as a no-op
unless that was proved.
Step 4: Offer Reproducible Project State
After adding or changing project skills, check for .tink/skills.toml and
.tink/skills.lock. If absent, ask whether the user wants a reproducible
manifest. Only after approval, run tink skill lock, supplying
--source NAME=PATH for each local skill. Each local source path must resolve
inside the project. If skill verify reports a legacy
version-1 lock digest, ask before rerunning skill lock; that explicit relock
rewrites version 2 and includes raw Unix path bytes and portable executable modes. If
both files already exist, use tink skill sync only when the user requested
restoration.
Expected: Manifest files are created or synchronized only with explicit
approval; divergent content remains untouched.
On failure: Report missing local source mappings or divergence and stop.
Do not guess a source or overwrite a project tree. If an unexpected operational
error interrupted sequential sync publication, report the potentially partial
state and explain that rerunning the same idempotent tink skill sync is the
recovery path; ask before retrying.
Step 5: Configure Shell Completion When Requested
Use the shell-specific command only after the user asks for completion:
- Zsh: after
autoload -Uz compinit and compinit, use
source <(COMPLETE=zsh tink).
- Bash: use
source <(COMPLETE=bash tink).
- Fish: use
COMPLETE=fish tink | source.
Expected: Completion is configured for the current requested shell session
only. Editing a startup file for future sessions is a separate filesystem
mutation and requires authority for that exact file.
On failure: Report the shell and command failure. Do not edit unrelated
shell configuration.
Step 6: Refresh Manage Tink When Separately Authorized
After any binary update or observed contract mismatch, explain that the live
skill may be stale. Do not replace it automatically. Before destroy, compare
the active tink destroy --help boundary with this skill's ownership contract;
if it is broader, stop and renew approval. If the user explicitly authorizes
refreshing the embedded package, run tink skill refresh manage-tink.
Expected: Missing copies are installed, current copies report Unchanged,
and differing receipt-free copies are atomically replaced. The project,
library, and catalog are reconciled, and the binary's embedded copy becomes
the live project skill. A same-named skill with remote provenance is refused.
On failure: Stop after the failing command and report which project,
library, and catalog states were proven. Do not conceal a partially completed
publication.
Step 7: Prove the Post-state
- After
init, run tink skill check, project/catalog/library listings, and
verify the requested optional guidance or bundle state.
- After add, promotion, refresh, or sync, run
tink skill check and verify the
affected project, catalog, and library entries. After sync, also run
tink skill verify.
- After harvest, use its summary and
tink library list; project check does not
prove a library-only mutation.
- After
skill lock, run tink skill verify.
- After skillset add or refresh, run
tink skill check, tink skillset list,
and tink skillset list --library.
- After
skill remove, verify project/catalog absence and library retention.
- After
skillset remove, verify project absence and library presence; its
external definition should remain.
- After update, resolve the active binary and probe its exact version. After
refreshing embedded
manage-tink, run project/catalog/library listings plus
tink skill check; check compares the live payload with the active binary.
- After
destroy, confirm .agents/skills/ is gone, .agents/ is gone only if
it became empty, ZEN.md and AGENTS.md are preserved, unrelated .agents/
siblings remain, and the project has no catalog rows; do not run skill check.
Expected: The proof matching the mutation is reported to the user.
On failure: Report the unproven post-state and stop. Never claim success
from the mutation command alone.
Validation
Common Pitfalls
- Treating the home library as an agent discovery root.
- Treating a receipt-backed library skillset as a standalone skill.
- Treating a source with a regular or dangling
.tink-skillset.json entry as a
standalone skill; use tink skillset add NAME-skillset instead.
- Inferring a skillset suffix or definition from inspection output.
- Combining a binary update with project-skill replacement without approval.
- Treating external skillset-definition authoring as authority to edit receipts,
derived by-project catalog metadata, or divergent managed trees.
- Treating command completion as proof of the requested outcome.
Related Skills
skill-scout — Research candidate skills with evidence before choosing one
to add through Tink.
Authority
| User said… | Authorizes… |
|---|
| Set up / init Tink (no extras) | tink init --no-zen --no-tink-skills (embeds manage-tink) |
| …and ZEN / tink-skills / skip manage-tink | Only the matching --with-* / --no-* flags |
| Add / list / check / refresh / remove … | The matching tink skill … command |
| List catalog | tink skill list --catalog |
| List library / promote from library | tink library list (tink skill list --library compatibility alias) / tink skill add NAME |
| Harvest harness skills into library | tink skill harvest |
| Inspect a public GitHub skill source | tink inspect GITHUB_URL (read-only) |
| List project / library skillsets | tink skillset list / tink skillset list --library |
| Add / refresh / remove a canonical skillset | The matching tink skillset … NAME-skillset command |
| Author a pinned skillset definition | Only the exact catalog/by-skillset/NAME-skillset/meta.json input; does not authorize install |
| Configure shell completion | Only the matching shell command |
| Persist shell completion | Only the exact startup file the user authorizes |
| Lock / verify / sync reproducible state | Only the matching tink skill … command; lock requires a project-contained source mapping for each local skill |
| Refresh embedded manage-tink | tink skill refresh manage-tink |
| Remove one project skill | tink skill remove NAME |
| Update the Tink binary | tink update only; refreshing embedded manage-tink requires separate authority |
| Remove managed project skills / destroy Tink setup | tink destroy (TTY) or tink destroy --yes (scripts); guidance and unrelated siblings are preserved |
"Set up Tink" does not authorize ZEN, tink-skills, refreshing embedded
manage-tink, or destroy.
Ownership (always)
- Leave
.tink-source.json untouched — it is the refresh receipt.
- Leave
.tink-skillset.json untouched — it is skillset ownership and digest
evidence. Its presence takes precedence over a root SKILL.md; standalone
library commands must not expose, promote, or replace that root.
- Skillset definitions under
catalog/by-skillset/ are the only externally
authored Tink-home metadata. Create or change one only with explicit authority;
never infer its revision or members from an inspection proposal.
- On a refusal, stop and report it. Authorized deletes are only:
tink skill remove NAME → .agents/skills/<name>/ and drops that name
from the by-project catalogtink skillset remove NAME-skillset → only the receipt-backed project
skillset tree; preserves its catalog definition and library copytink destroy → .agents/skills/, then .agents/ only if empty, and
drops this project's by-project catalog entry; preserves ZEN.md,
AGENTS.md, and unrelated .agents/ siblings
- Treat local skills as non-refreshable unless they carry a valid receipt.
- Never execute code from a skill while Tink manages it.
- Library (
~/.tink/skills/) is not an agent discovery root; use
tink skill add NAME instead of copying or linking it.
- Skillsets are nested at
.agents/skills/NAME-skillset/<member>/SKILL.md; each member remains a valid
named skill. Never flatten, merge, or manually copy members.
- Do not prune the library by hand. Project removals preserve library trees.
- Do not run concurrent Tink mutations against one project or shared Tink home;
Tink has no inter-process lock.
