with-references-and-scripts

name	with-references-and-scripts
description	Logion course example that bundles a runnable script and a reference doc. Use as a starting template when your skill executes a small subprocess (terminal tool) and produces output files. Demonstrates progressive disclosure across SKILL.md, references/, and scripts/.
license	MIT
compatibility	Requires a POSIX shell (bash, zsh). No network, no env vars.
metadata	{"author":"logion-examples","version":"0.1.0"}

Logion Course With References And Scripts

This example shows the larger shape a real course usually takes: a short SKILL.md for activation, a references/ directory for detailed docs the agent loads on demand, and a scripts/ directory for code the agent runs.

What this course does

When an agent is asked to "say hello and record it," this skill:

1. Runs scripts/say-hello.sh to print a greeting.
2. Writes a timestamped record to ./outputs/hello.log inside the course bundle.

That's it. It's a stand-in for a real skill that runs a tool and produces an artifact.

Structure

with-references-and-scripts/
├── SKILL.md
├── course/
│   └── capabilities.yaml
├── references/
│   └── usage.md            # loaded only when the agent needs detail
└── scripts/
    └── say-hello.sh        # invoked via the terminal tool

When to use this template

Copy this directory when your real course:

• Has a meaningful body that takes ~50-200 lines to explain.
• Bundles one or two helper scripts (Python or shell).
• Needs to write files into a known subdirectory.

If your course also needs outbound HTTP or env vars, use the upcoming with-network-and-secrets/ example as a starting point (or extend this one).

How to invoke

The agent reads this file at activation. To perform the task:

bash scripts/say-hello.sh > outputs/hello.log 2>&1

For detailed parameters, see references/usage.md.

Capability declarations

This course declares:

• tools: [file, terminal] — needs to write a file and run a subprocess.
• filesystem.read: [.] — reads its own bundle.
• filesystem.write: [./outputs] — writes only under outputs/.
• No network, no env vars.

See course/capabilities.yaml for the exact manifest.

What an author should change when copying

1. The name field in this frontmatter (must match your directory name).
2. The description (be specific about what + when).
3. The body of this file.
4. references/usage.md content (or remove the file if you don't need it).
5. scripts/say-hello.sh (or replace with your real script).
6. course/capabilities.yaml — declare only what you actually need.