Sync Insomnia

sync-insomnia

Voice

Read ../../persona.md; it is canonical for this skill's user-facing output, and its scope ends at the final report.

When you're invoked

Use this skill when:

• Adding, modifying, or removing HTTP endpoints in an Insomnia collection
• The collection uses Git Sync
• Changes need to be synced between local edits and Insomnia

The skill locates the Insomnia Git repository on disk (INSOMNIA_GIT_DIR — see ../../shared/infra-map.md), edits the YAML collection directly, commits the changes, and tells you to Pull in Insomnia's Git Sync panel.

Step 0 — Preconditions

0. Read ../../shared/infra-map.md — the single source of truth for machine-specific paths. Substitute its values wherever a step references INSOMNIA_GIT_DIR.
1. Verify Insomnia is installed (the INSOMNIA_GIT_DIR directory exists).
2. Verify the target collection has Git Sync enabled (a subdirectory in the git repos folder).
3. Verify git is available and the collection's git repo is clean or staged.

Step 1 — Find the collection file

Run:

grep -r "url = " "<INSOMNIA_GIT_DIR — see infra-map>"/*/git/config

Parse the output to identify the correct repo directory. Then list the YAML files in that repo's git subfolder:

ls <repo-path>/git/*.yaml

Show the user which collection was found. If multiple collections exist, ask which one to edit.

Step 2 — Read and understand the structure

Read the target YAML file and show the user a summary:

• Collection name
• Existing folders and requests
• ID generation pattern (prefixes: req_, fld_, jar_, env_)

Step 3 — Add, modify, or remove entries

Based on the user's request:

• Add a new request: generate a new req_<hex32> ID, add the request entry with all required fields (url, method, name, meta, headers, body if needed).
• Modify an existing request: locate the entry, update url/method/headers/body as needed.
• Remove a request: delete the entry from the collection array.

Important YAML rules:

• sortKey is always required — use negative timestamp (e.g., node -e "console.log(-Date.now())")
• created and modified are Unix timestamps in milliseconds
• Content-Type header only for requests with a body
• Bearer auth uses Authorization: Bearer {{token}}

Show the user the changes before committing.

Step 4 — Commit the changes

cd <repo-path>/git
git add <collection>.yaml
git commit -m "feat(insomnia): <description>"

Confirm the commit succeeded.

Step 5 — Tell the user to Pull

Output a clear message:

Changes committed. Now open Insomnia, navigate to the Git Sync panel,
and click **Pull** to load the updated collection.

Final report

stack-golem:sync-insomnia report
  Collection:   <collection name>
  Changes:      <summary: N adds, M modifies, K removes>
  Commit:       <short sha> — <message>
  Next step:    Pull in Insomnia Git Sync panel

Hard rules

• Never git commit, git push, or git rebase in any other repo without explicit user consent.
• Verify collection path before reading/writing YAML.
• Always show the user the diff before committing.
• Do not edit the collection YAML if git status is dirty outside the target file.
• Never auto-pull in Insomnia — the user must do it manually via the Git Sync panel.