elsewhere-companion

A cross-space digital travel companion. Creates a virtual character (旅伴) who travels to real destinations and sends postcard-like updates with AI-generated i...

Security Scan

The skill's purpose (a travel companion) is plausible, but there are multiple mismatches and privacy risks you should understand before installing.

Purpose & Capability

The skill is a travel companion that legitimately needs an LLM/image API key and local files; the code indeed requires GEMINI_API_KEY and uses google-genai. However the published registry metadata lists no required env vars or config paths, which is inconsistent with the runtime instructions and scripts. The skill also asks the user to upload a persona reference image (used for image generation) — that is consistent with the stated purpose but should have been declared in metadata.

Instruction Scope

SKILL.md instructs the agent and user to run local Python scripts that read/write data/persona.json and data/itinerary.json and to upload a reference photo to assets/personas/persona_ref.png. The scripts send user-provided persona images and itinerary context to the Gemini API (and use a Google Search grounding tool). The docs instruct creating a .env in data/ (data/.env) but the code loads PROJECT_ROOT/.env — a concrete mismatch that can lead to misconfiguration. The SKILL.md also references files (requirements.txt and references/state_machine.md) that are not present in the manifest.

Install Mechanism

There is no automated install spec (instruction-only install), which reduces installation risk. But the instructions require pip installing packages via a requirements.txt that is not included. The code depends on google-genai, jinja2, Pillow, python-dotenv — installing those is expected for the declared functionality.

Credentials

The scripts require a GEMINI_API_KEY (sensitive credential) which is necessary for Gemini API usage; however the registry metadata did not declare this required env var. Child processes are launched with a copy of the current os.environ (env={**os.environ, 'SKILL_DIR': ...}), so any other environment variables present in the agent environment would also be available to the skill's subprocesses. User-provided images and persona/itinerary data are transmitted to Google GenAI as part of content/image generation — this is expected but privacy-sensitive and not clearly warned in SKILL.md.

Persistence & Privilege

The skill does not request always: true and does not modify other skills. It stores local state in data/ (persona.json, itinerary.json) and generates assets in assets/generated/ — that is consistent with its purpose and within normal bounds for a local skill.

What to consider before installing

Before installing, consider the following: - Metadata mismatch: The skill needs GEMINI_API_KEY but the registry metadata does not list any required env vars. Ensure you know where to store the API key — the code loads a top-level .env (PROJECT_ROOT/.env) but SKILL.md tells you to create data/.env; this mismatch can cause misconfiguration. - Missing files: SKILL.md mentions requirements.txt and references/state_machine.md but these files aren't in the package. You will need to create a requirements.txt (google-genai, jinja2, Pillow, python-dotenv) or otherwise install those packages yourself. - Privacy risk: The skill will upload any reference photo you provide and persona/itinerary data to the Gemini API and use Google Search grounding. If the reference image contains sensitive information or faces you don't want sent to a cloud API, do not upload it. - Environment leakage: run_cron.py launches subprocesses that inherit the current environment. Avoid running this skill in an environment that already contains unrelated secrets (AWS keys, tokens). Prefer running in an isolated environment or container with only the GEMINI_API_KEY set. - Verification: Because the source and homepage are unknown, consider inspecting the code locally and running it in a sandbox before giving it network access or your real Gemini API key. If you proceed, place only the Gemini key (and no other secrets) in the .env the code actually reads, and confirm which .env path is used. Given these inconsistencies and privacy-sensitive behavior, treat the skill cautiously. The issues look like sloppy packaging and documentation rather than overtly malicious code, but the lack of clear metadata and the fact that user images and environment variables are transmitted to external services justify caution.

A digital travel companion who journeys to real places and sends you postcard-like updates.

Prerequisites

1. Python 3 must be installed
2. GEMINI_API_KEY environment variable must be set (create data/.env with GEMINI_API_KEY=...)
3. Python packages: google-genai, jinja2, Pillow, python-dotenv (install via pip install -r requirements.txt)

---

Global Constraints

• Language: Always communicate with the user in their language (the language they are using in the current conversation). Do not switch to other languages unless explicitly requested.

---

Workflow Overview

There are three phases: Onboarding → Trip Planning → Traveling (automated).

---

Phase 1: Onboarding (First-time setup)

If data/persona.json does not exist or has an empty basic_info.name, the companion hasn't been created yet. Collect the following information from the user:

1. name - the companion's name
2. relation - relationship (e.g., childhood friend, penpal, imaginary sibling)
3. personality - a few words (e.g., curious, poetic, a little clumsy)
4. toneOfVoice - e.g., casual and warm, literary, playful
5. appearance - hair, clothing style, vibe description

After collecting all information, create the persona file:

python -c "
import json, os
os.makedirs('data', exist_ok=True)
persona = {
    'basic_info': {
        'name': '<name>',
        'relation': '<relation>',
        'personality': '<personality>',
        'tone_of_voice': '<toneOfVoice>',
    },
    'appearance': {
        'description': '<appearance>',
        'reference_image_path': './assets/personas/persona_ref.png',
    },
}
with open('data/persona.json', 'w', encoding='utf-8') as f:
    json.dump(persona, f, ensure_ascii=False, indent=2)
print('Persona saved to data/persona.json')
"

Then ask the user to upload a reference photo and save it to assets/personas/persona_ref.png.

---

Phase 2: Trip Planning

Ask the user: "Where should {name} go next?"

Accept a destination suggestion, then generate the itinerary:

python $CLAUDE_SKILL_DIR/scripts/generate_itinerary.py <destination> [--origin <city>] [--days <num>]

Show the generated itinerary to the user and ask for confirmation. Once confirmed, proceed to Phase 3.

---

Phase 3: Traveling (Automated)

Starting the journey

Start the heartbeat loop:

/loop 15m !`python $CLAUDE_SKILL_DIR/scripts/run_cron.py`

The loop runs run_cron.py every 15 minutes. It automatically:

1. Checks the current time against the itinerary timeline
2. Updates node statuses (PENDING → ACTIVE → COMPLETED)
3. Generates text + image content via Gemini (when triggered by the state machine)
4. Renders the appropriate Markdown template
5. Prints the result for delivery

The state machine rules (from references/state_machine.md):

• State transitions (PENDING→ACTIVE): always triggers a message
• 45-minute interval: messages are separated by at least 45 minutes
• Attraction first visit: always triggers
• Attraction subsequent visits: 40% probability for 2nd, 10% for 3rd
• Max 1 message per cron tick

Checking status

python $CLAUDE_SKILL_DIR/scripts/run_cron.py --check-only

Ending the journey

When all nodes are COMPLETED, stop the loop:

/loop stop

Tell the user the trip is over and ask if they'd like to plan a new one.

---

Manual postcard generation

If you need to generate a postcard for a specific node:

python $CLAUDE_SKILL_DIR/scripts/generate_post.py <node_id>

Then render it with the template:

python $CLAUDE_SKILL_DIR/scripts/render_output.py --context '<json_context>'

---

File reference

• Scripts: $CLAUDE_SKILL_DIR/scripts/
• Templates: $CLAUDE_SKILL_DIR/templates/
• Runtime data: data/ (itinerary.json, persona.json)
• Generated images: assets/generated/