with-scripts

With-Scripts: Bundled Gmail CLI Example

This example shows how to ship a real working tool inside a Logion course bundle. The course owns its codebase — there is no pip install, no npm install, no transitive dependency tree. Everything the agent needs to call the Gmail API lives in this bundle and was reviewed once when the course was published.

This is the canonical pattern for replacing "tell the user to install my CLI from npm" with "the course bundles the CLI."

Structure

with-scripts/
├── SKILL.md                  # this file
├── course/
│   └── capabilities.yaml     # file + terminal + web; gmail.googleapis.com; OAuth env
├── scripts/                  # thin entrypoints the agent invokes
│   ├── search.sh             # search messages
│   └── list-labels.sh        # list user labels
└── src/
    └── gmailcli/             # actual implementation
        ├── __init__.py
        ├── __main__.py       # python -m gmailcli {search,labels}
        ├── api.py            # Gmail REST client (stdlib urllib only)
        └── auth.py           # reads OAuth token from env

scripts/ holds short entrypoints — bash wrappers that set PYTHONPATH and invoke the Python module. src/ holds the real implementation. The separation is deliberate:

• The agent only invokes scripts/search.sh "query". Simple, discoverable surface.
• The bulk of the logic — API calls, error handling, JSON parsing — lives in src/gmailcli/. Reviewable, testable, organized.
• The bundle stays self-contained: stdlib only (urllib.request, json), no pip install anywhere.

When to use this template

Copy this structure when your course:

• Ships a non-trivial amount of code (more than one short script).
• Wants scripts/ to remain a clean surface for the agent to discover commands.
• Has real implementation worth organizing into modules.

If your course is a single 50-line script, the simpler with-references-and-scripts/ example is a better starting point.

How to use