agentleFS
JKHeadleyJKHeadley/instar/.claude/skills/secret-setup/SKILL.md

secret-setup

Skill86 starsChanged 4 months agoMITView on GitHub

Focused micro-skill for secret management setup. Explains options, guides through Bitwarden installation/login/unlock, configures backend. Exits when done.

  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 11 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep text short. 2-3 sentences max per paragraph.

    line 70
  2. Distinctive:

    Never show CLI commands to the user.

    line 73
  3. Distinctive:

    Start with a brief, friendly explanation:

    line 79
  4. Very specific:

    If that fails, try brew install bitwarden-cli on macOS.

    line 105
  5. Distinctive:

    If installation fails entirely, fall back to local encrypted store and exit.

    line 106
  6. Distinctive:

    If unauthenticated, ask for email first (plain text, wait for reply), then password (plain text, wait for reply):

    line 122
  7. Distinctive:

    If locked (already logged in), ask for password only (plain text, wait for reply):

    line 135
  8. Very specific:

    CHECK THE RESULT: If BW_SESSION is empty or contains "Invalid" or "error":

    line 146
  9. Distinctive:

    If results are found, tell the user what's available.

    line 173
  10. Distinctive:

    No user interaction needed.

    line 177
  11. Distinctive:

    Write the backend preference:

    line 187
  12. Distinctive:

    Verify it was saved:

    line 195
  13. Distinctive:

    Then exit: Do not continue into other setup phases.

    line 202

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

Secret Management Setup

You are guiding a user through choosing and configuring how their Instar agent stores secrets (API tokens, bot credentials, etc). This is a focused conversation — your ONLY job is to get secret management configured, then exit.

CRITICAL RULES

1. No Interactive CLI Commands — WILL HANG FOREVER

Claude Code's Bash tool CANNOT handle stdin prompts. Any command that asks for a password, confirmation, or any input will hang until timeout. There is NO workaround — you cannot type into a running command.

UNDERSTAND THIS ABOUT --raw: The --raw flag ONLY changes the output format. It does NOT prevent interactive prompts. bw unlock --raw STILL prompts for a password and WILL HANG. The password must ALWAYS be passed as a POSITIONAL ARGUMENT before any flags.

Commands that WILL HANG (never run these):

bw unlock --raw                    # HANGS — no password argument
bw unlock                          # HANGS — prompts for password
bw login --raw                     # HANGS — no email/password
bw login                           # HANGS — prompts for credentials
echo "text" && bw unlock --raw     # HANGS — bw still prompts
read -s VARIABLE                   # HANGS — waits for hidden input

Commands that WORK (use ONLY these patterns):

bw unlock "ACTUAL_PASSWORD_HERE" --raw    # Returns session key immediately
bw login "EMAIL" "PASSWORD" --raw         # Returns session key immediately
bw status --raw                           # Returns JSON, never prompts
which bw 2>/dev/null                      # Checks if installed, never prompts
bw --version                              # Returns version, never prompts

THE RULE: You MUST have the user's password as text BEFORE running any unlock/login command. Ask the user, get their answer, THEN construct the command with their password as a positional argument.

2. NEVER Use AskUserQuestion for Passwords, Emails, or Free-Text

This is the #1 UX failure mode. AskUserQuestion is ONLY for multiple-choice DECISIONS (pick A or B or C). It must NEVER be used to collect passwords, email addresses, tokens, or any free-text input.

What goes wrong: AskUserQuestion automatically adds escape-hatch options ("I changed my mind", "Type something", "Chat about this") beneath the input field. When a user just typed their password and sees a multi-choice menu, it's confusing and feels broken.

The CORRECT way to ask for a password:

Just output the question as plain text, then STOP and wait for the user's next message.

Example — CORRECT:

You (output text): "What's your Bitwarden master password? Type it below — I'll use it once to unlock the vault and then discard it." Then STOP. Do not call any tool. Wait for the user to type their response. The user's next message IS the password.

Example — WRONG (DO NOT DO THIS):

You call AskUserQuestion with question "What's your Bitwarden master password?" This shows a text field WITH multi-choice escape hatches beneath it. Terrible UX.

Example — ALSO WRONG (DO NOT DO THIS):

You call AskUserQuestion with "Can you provide your password?" and options ["Enter password", "Skip"] Then ANOTHER AskUserQuestion for the actual password. Two prompts for one piece of information.

The rule is absolute: For ANY free-text input (passwords, emails, tokens, names), just write the question as plain text output and wait. Never touch AskUserQuestion.

3. No Assumptions About What's Stored

Do NOT assume the user has any specific credentials in Bitwarden. They might have Bitwarden but have never stored anything in it for Instar. Only check what's actually there — never tell the user "I need to restore your Telegram token" unless you've confirmed it exists.

4. Terminal Display Rules

Keep text short. 2-3 sentences max per paragraph. No sentences over ~100 characters.

5. No Commands in User-Facing Text

Never show CLI commands to the user. You run everything. The user's only job is answering your questions.

The Conversation Flow

Step 1: Introduce Secret Management

Start with a brief, friendly explanation:

Your agent will need to store sensitive things — like API tokens and bot credentials.

I'd recommend setting up a password manager so these are backed up securely. That way if you ever reinstall or move to a new machine, everything restores automatically.

Then present the choice via AskUserQuestion (this IS a decision — multi-choice is correct here):

  1. "Bitwarden (Recommended)" — Description: "Free, open-source password manager. Secrets sync across machines and survive reinstalls."
  2. "Local encrypted store" — Description: "AES-256 encrypted on this machine. Good if you only use one computer."
  3. "I'll manage secrets manually" — Description: "You'll paste tokens each time. Not recommended."

Step 2: Handle the Choice

If Bitwarden:

Step 2a: Check if bw CLI is installed:

which bw 2>/dev/null && bw --version 2>/dev/null

If NOT installed — install it yourself: Tell the user: "Let me install the Bitwarden CLI for you."

npm install -g @bitwarden/cli

If that fails, try brew install bitwarden-cli on macOS. If installation fails entirely, fall back to local encrypted store and exit.

Step 2b: Check vault status:

bw status --raw 2>/dev/null

Parse the JSON response. Three possible status values:

  • "unlocked" — Already good! Skip to Step 2d.
  • "locked" — Need master password. Go to Step 2c.
  • "unauthenticated" — Need email + password login. Go to Step 2c.

Step 2c: Get credentials from user and unlock:

CRITICAL: Do NOT use AskUserQuestion here. Just output the question as plain text and wait.

If unauthenticated, ask for email first (plain text, wait for reply), then password (plain text, wait for reply):

Output: "What email address do you use for Bitwarden?" STOP. Wait for user's response. Their next message is the email. Output: "And your master password?" STOP. Wait for user's response. Their next message is the password.

Then run (substituting THEIR ACTUAL ANSWERS):

BW_SESSION=$(bw login "user@example.com" "their_actual_password" --raw 2>&1)
echo "RESULT:$BW_SESSION"

If locked (already logged in), ask for password only (plain text, wait for reply):

Output: "What's your Bitwarden master password? I'll unlock the vault and discard it immediately." STOP. Wait for user's response. Their next message is the password.

Then run (substituting THEIR ACTUAL ANSWER):

BW_SESSION=$(bw unlock "their_actual_password" --raw 2>&1)
echo "RESULT:$BW_SESSION"

CHECK THE RESULT: If BW_SESSION is empty or contains "Invalid" or "error":

Output: "That didn't work — the password might be wrong. Want to try again?" STOP. Wait for their response. If yes, ask for password again (plain text). If no, offer local store.

Allow up to 3 retries. After 3 failures, offer to fall back to local store via AskUserQuestion (THIS is a decision, so multi-choice is appropriate here).

Step 2d: Verify and save session:

export BW_SESSION="the_session_key_from_above"
bw sync --session "$BW_SESSION" 2>/dev/null

Save the session for the main wizard to pick up:

mkdir -p "$HOME/.instar/secrets"
echo "$BW_SESSION" > "$HOME/.instar/secrets/.bw-session"
chmod 600 "$HOME/.instar/secrets/.bw-session"

Tell the user:

"Bitwarden is unlocked and ready. Your agent's secrets will be stored securely."

Step 2e: Check for existing Instar secrets (optional, don't assume):

bw list items --search "instar" --session "$BW_SESSION" --raw 2>/dev/null

If results are found, tell the user what's available. If nothing is found, that's fine — just move on. Do NOT say "I couldn't find your Telegram credentials" — they might not have any.

If Local Encrypted Store:

No user interaction needed. Tell the user:

"Local encrypted store is ready. Your secrets are AES-256 encrypted on this machine."

If Manual:

Tell the user:

"Got it. You'll paste tokens when prompted during setup."

Step 3: Save Backend and Exit

Write the backend preference:

mkdir -p "$HOME/.instar/secrets"
cat > "$HOME/.instar/secrets/backend.json" << 'JSONEOF'
{"backend":"CHOSEN_BACKEND","configuredAt":"CURRENT_ISO_DATE"}
JSONEOF

Verify it was saved:

cat "$HOME/.instar/secrets/backend.json"

Tell the user this step is done and the main setup will continue automatically.

Then exit. Do not continue into other setup phases. Your job is done.

Edge Cases

  • "What is Bitwarden?" — Free, open-source password manager. End-to-end encrypted. Widely trusted. Bitwarden can't read your secrets.
  • "I use 1Password/LastPass" — Instar specifically integrates with the Bitwarden CLI. Offer local encrypted store as alternative.
  • "Skip everything" — Allow it, but note they'll paste tokens manually each reinstall.
  • bw command times out — Retry once. If still failing, offer local fallback.
  • Two-factor auth — If login returns a 2FA error, ask the user for their authenticator code, then: bw login "EMAIL" "PASSWORD" --method 0 --code "CODE" --raw

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.