inspiration-importer - SKILL.md Agent Skill

name: inspiration-importer version: 2.0.0 description: | Import content into inspiration/ for knowledge review. Supports GitHub repos, gists, URLs, and local files. Summarize the import and ask what to do next. allowed-tools: - Shell - Read - Write - Edit - Delete - LS - Glob - Grep - AskUserQuestion

Inspiration Importer

Import external content into inspiration/ for knowledge review, then produce a structured summary so the user can decide next actions.

Your Task

When given a source (GitHub repo, gist, URL, or file path):

Import the content — Place it under inspiration/
Summarize the content in chat — Include required tables
Ask what to do next — Offer clear options and wait for a choice
Execute the user's chosen option

Supported Sources

GitHub repo: https://github.com/owner/repo or owner/repo
GitHub repo path: https://github.com/owner/repo/tree/branch/path
GitHub gist: https://gist.github.com/owner/hash
Raw URL: Any URL to a markdown or text file
Local file/folder: Path to content already on disk

Process

Step 1: Parse the Input

For GitHub repos, extract:

Owner
Repo name
Branch (default: repo default branch)
Optional path (for partial imports)

For other sources, identify the content type and origin.

Step 2: Prepare the Destination

Destination: inspiration/ at the repo root.

Use a unique folder name to avoid collisions:

inspiration/
└── {owner}-{repo}/
    ├── _SOURCE.md      # Tracking file
    └── ...             # Imported content

If the destination exists:

Ask the user whether to replace, update, or cancel.

Step 3: Import the Content

For GitHub repos — use git submodule:

git submodule add https://github.com/OWNER/REPO inspiration/OWNER-REPO

This:

Creates a .gitmodules entry (or appends to existing)
Clones the repo at its current HEAD
Tracks the exact commit in the parent repo

To update an existing submodule later:

cd inspiration/OWNER-REPO && git pull && cd ../..
git add inspiration/OWNER-REPO && git commit -m "chore: update OWNER-REPO submodule"

For other sources — download directly:

# Gist
curl -sL https://gist.githubusercontent.com/OWNER/HASH/raw/ > inspiration/OWNER-gist-HASH/content.md

# Raw URL
curl -sL URL > inspiration/source-name/content.md

Step 4: Create Source Tracking File

Create inspiration/{source}/_SOURCE.md:

# Source Information

This directory contains imported content for knowledge review.

- **Source**: SOURCE_URL
- **Type**: repo | gist | url | local
- **Branch**: BRANCH (if applicable)
- **Commit**: COMMIT_HASH (if applicable)
- **Synced at**: TIMESTAMP

## File Mapping

| Local File | Upstream Path |
|------------|---------------|
| README.md | README.md |
| (local addition) | _SOURCE.md |

## Notes

Re-run the inspiration-importer skill to update this import.

Step 5: Summarize for the User

Read and summarize the import. Provide:

Overview — 2-5 bullets: purpose, structure, key entry points
Skills table — All .cursor/skills/*/SKILL.md entries
Columns: Skill, Location, Purpose
Docs table — All docs/**/*.md plus root README.md (if present)
Columns: Doc, Location, Purpose
Other notable assets — Scripts, templates, prompts, workflows, configs
Columns: Asset, Location, Purpose

Keep descriptions short and factual. Use the file description, first heading, or intro paragraph to infer purpose. If unclear, say "Unclear from file."

Step 6: Ask What to Do Next

Ask the user what to do with the imported knowledge and offer options:

Import skill(s) into .cursor/skills/
Add knowledge to docs/ (summarized and reformatted to match this repo)
Do nothing (leave the import as-is for reference)
Delete the import
Something else (ask)

Wait for the user's choice, then proceed.

Example Usage

Import a GitHub repo:

Import https://github.com/owner/repo

Import a specific path from a repo:

Import https://github.com/owner/repo/tree/main/docs

Import a gist:

Import https://gist.github.com/owner/abc123

Output

After importing, report:

Source: Full source URL
Commit: Hash that was synced (if applicable)
Import location: inspiration/{source}/
Summary: Overview + required tables
Next step question: Ask the user to choose an option

Edge Cases

Large repos: Import fully; summarize only key files
Binaries: Keep in import but skip reading them for summary
Missing docs/skills: Say "None found"
Existing import: Ask before replacing or updating

Broken submodule (nested .git but no .gitmodules entry): Fix with:

git rm --cached inspiration/OWNER-REPO
git submodule add https://github.com/OWNER/REPO inspiration/OWNER-REPO