Source refs

Source refs locate shared agents and caps in Toolang 0.4.0. A cap identity such as skill/reviewer selects an available cap; a source such as gh:owner/reviewer locates content to acquire. Remote acquisition uses HTTPS without interactive login and does not use GitHub CLI credentials.

Reference	Example	Used for
Source Ref	`gh:acme/reviewer`	Acquire an agent or cap definition
Cap identity	`skill/reviewer`	Query or allow an effective cap
Runnable ref	`agic:review`, `flow:review`	Select an executable
Agent selector	`alice`, `script.too`, a Source Ref	Select a resident, roaming, or visiting agent
Instance address	`NAME@CODE`, `script.too@CODE`	Continue in one reported instance; see instance selection

Short refs

GitHub shorthand is explicit:

gh:OWNER/NAME
gh:OWNER/REPO/NAME

github: is an alias for gh:. The two-part form searches the owner's conventional repositories on their default branches. Candidates are tried in this order:

Kind	Repository and path candidates
Agent	`agents/agents/NAME.too`, then `agents/NAME.too`
Skill	`agents/skills/NAME`, `agent-skills/NAME`, `agent-skills/skills/NAME`, `skills/NAME`, `skills/skills/NAME`
Psyche	`agents/psyches/NAME.md`, `agent-psyches/NAME.md`, `psyches/NAME.md`
Service	`agents/services/NAME.md`, `agent-services/NAME.md`, `services/NAME.md`
Prompt	`agents/prompts/NAME.md`, `agent-prompts/NAME.md`, `prompts/NAME.md`

Each entry is relative to OWNER/. Skill directories must contain SKILL.md.

The three-part form uses only the specified repository. Agents probe agents/NAME.too, then NAME.too. Skills probe skills/NAME, then NAME; dedicated agent-skills and skills repositories prefer NAME first. Other cap kinds probe KINDS/NAME.md, then NAME.md; their dedicated agent-KINDS and KINDS repositories use NAME.md.

too gh:briceyan/gus chat
too clone gh:briceyan/gus gus
too alice skill add gh:briceyan/review

Bare remote refs such as owner/name, and the old oh: and openhat: schemes, are unsupported. Use a prefix even when the intended repository is obvious.

Exact GitHub refs

Specify a complete path and revision to bypass shorthand probing:

github://OWNER/REPO/PATH@REV
gh:OWNER/REPO/PATH@REV
github:OWNER/REPO/PATH@REV

REV may be a branch, tag, or commit. Canonical github:// refs require it. Acquisition resolves GitHub revisions to a full commit SHA in prepared State. Pin an immutable commit when repeatable content is required.

Without @REV, gh: and github: accept only the two- or three-part shorthands above. A deeper repository path needs an explicit revision. For branches containing /, prefer the explicit ref form, for example github://acme/agents/skills/reviewer@feature/review; a regular GitHub URL uses its first path segment after tree or blob as the revision.

with skill github://acme/agents/skills/reviewer@v1.0.0
 
agic review:
  Review the supplied change.

A skill source denotes its directory. A GitHub skill path ending in SKILL.md is normalized to its parent directory. GitHub skill acquisition includes sibling files; file-backed caps point to individual Markdown files.

GitHub URLs

Tree, blob, and raw-content URLs are exact sources:

too alice skill add https://github.com/acme/agents/tree/main/skills/reviewer
too alice service add https://github.com/acme/agents/blob/main/services/search.md
too clone https://github.com/acme/agents/blob/main/reviewer.too reviewer

Their URL supplies the path and revision; repository-layout probing does not apply. Source refs and URLs use the same cap-kind-specific acquisition rules.

Direct URLs

An HTTP(S) URL can supply an agent .too file or a file-backed cap:

too https://toolang.ai/lex.too chat
too clone https://toolang.ai/lex.too lex
too alice psyche add https://example.com/concise.md

Remote agent sources require a .too path. For HTTP skills, use a directory URL or its SKILL.md URL; plain HTTP acquisition fetches SKILL.md only. Use a GitHub directory source when the skill needs accompanying files. HTTP sources are captured by content; they do not acquire a Git commit identity.

Source identity and reuse

Authored configuration keeps the declared source; prepared State records its resolved ref and captured content. Existing compatible acquisitions can be reused, so a branch name or HTTP URL is not a promise to fetch fresh upstream content on every command. Use a full commit SHA when source identity must stay fixed across preparations.

User action	Acquisition behavior in 0.4.0
Attach to a compatible running server, or select an explicit instance	Reuse that runtime/home; do not fetch its agent source
Prepare a visiting agent from its Source Ref or URL	Reuse a compatible verified program cache for one hour; otherwise resolve and fetch
Re-run or restart with unchanged cap declarations	Reuse compatible captured cap content when available; cap acquisitions have no automatic TTL refresh
Add a cap that is already configured	Report a conflict; `add` is not an update command
Remove and re-add a cap	Change its declarations; this is not a general force-refresh API
Change the declared URL or pin to a different commit	Select a new source acquisition

An expired visiting program cache is checked during preparation, not by periodically rewriting a running agent. There is no public too refresh command. For a reproducible update, change the declaration to the desired immutable commit and prepare or start the agent again.

A Source Ref locates content; it is not a resource-query identity or a runnable selector. Use skill/reviewer in cap queries, agic:review or flow:review to select a runnable, and the source forms on this page to acquire definitions. Local filesystem paths are not supported by with skill or configured remote cap refs; place local cap files in a root or agent-home cap directory instead.

Local .too paths select roaming script instances, while a resident name such as alice selects a managed local agent. These targets are distinct from remote Source Refs. See Run agent scripts and Create and run agents for their command forms.