portunus-drop
Skill2 starsChanged 32 days agoMITView on GitHub
Store a new secret (a value the user just gave you, or many at once) into Portunus's local vault. Use whenever a human hands you a credential, API key, or password and asks you to save/vault/remember it -- never store it anywhere else, and never echo it back once it's saved.
In this repository6 other files it gives its agents.
- ui/AGENTS.mdAGENTS.md
- ui/CLAUDE.mdCLAUDE.md
- portunus-askSkill
- portunus-promptSkill
- portunus-vault-auditSkill
- portunus-vault-setupSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 77
If the project doesn't yet have a vault binding configured (local vs.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Portunus Drop
Thin wrapper around portunus_drop/portunus_drop_bulk (MCP) or portunus drop/
drop-bulk (CLI) — the one place in Portunus where a secret value flows in from your
own context rather than out of it. That's inherent to being handed a brand-new secret to
store; it is not a boundary violation the way returning a value would be. Your
responsibility on this path is narrower but still absolute: never echo the value back to
the human or your own output after a successful store, never log it, never write it
anywhere Portunus itself doesn't manage.
Local-vault only. This creates a secret in the local encrypted vault — it does not
create anything in GCP Secret Manager or any other cloud provider. If the active backend
is gcloud/aws, the store fails closed with a clear error rather than silently doing
nothing.
When to use
- A human pastes you an API key/password/token and says "vault this," "save this in Portunus," "remember this key," or similar.
- You're importing many credentials at once (e.g. a batch of candidate passwords/keys someone wants tried against something later) — use the bulk form.
- You're setting up a new project's secrets from scratch and want them organized with
real metadata (
group/tags) from the start, not organized later.
When NOT to use
- You don't actually have the value yet — don't guess, don't generate one yourself. Portunus is a broker, not a credential generator.
- The secret already exists in GCP Secret Manager and you just need to reference it —
use
portunus discover/portunus_discoverto register a pointer to it instead; don't re-enter a value that's already stored elsewhere. - The secret should live in the cloud, not locally — Portunus has no write path into GCP Secret Manager yet. Say so plainly rather than silently storing it locally instead.
Usage — single secret
portunus_drop(
name="<short reference name>", # e.g. "gig-tracker-stripe-key"
sm_name="<vault key>", # e.g. "STRIPE_KEY"
value="<the value you were given>",
project="<project slug>", # optional but recommended
group="<hierarchical path>", # optional, e.g. "gig-tracker/stripe"
description="<what this is>",
purpose="<what it's for>",
)Or from the CLI: portunus drop <name> <sm_name> --stdin (value piped in, never an argv
flag) or --value-file <path>.
This lands the reference at state=dropped — fail-closed, not yet injectable. Follow up
with portunus_state(name, "enabled") (or portunus state <name> enabled) once you're
sure it's ready to be used.
Usage — many at once
portunus_drop_bulk([
{"name": "candidate-1", "sm_name": "CAND_1", "value": "..."},
{"name": "candidate-2", "sm_name": "CAND_2", "value": "..."},
...
])Or portunus drop-bulk entries.json (a JSON file, same entry shape). Returns
{"created": [names], "failed": [{"name", "error"}]} — a malformed entry doesn't abort
the rest of the batch.
After you've dropped a secret
If the project doesn't yet have a vault binding configured (local vs. GCP, sync mode),
consider the portunus-vault-setup skill next — especially before creating a first
secret in a brand-new project.
What you'll see
On success: {"name", "sm_name", "state"} (single) or {"created", "failed"} (bulk) —
never the value, on any path. On failure: a clear error string, still never the value.
Report success/failure to the human by name only — do not repeat the value back, even to
confirm it "looks right."
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

