agentleFS
mdostalmdostal/portunus/.claude/skills/portunus-drop/SKILL.md

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.

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
  1. Very specific:

    If the project doesn't yet have a vault binding configured (local vs.

    line 77

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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_discover to 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."

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.