@amaster.ai/pi-attachments

Pi extension that intercepts user input, resolves @-references to local resources, and injects their content into the prompt before the model sees it.

Hooks the input event of @earendil-works/pi-coding-agent. When a recognized mention appears in the user message, the original mention is stripped and replaced with structured context (skill block, attachment listing, or <system-reminder>). Image attachments are passed through as multimodal ImageContent.

Recognized mentions

Syntax	Resolves to
@path/to/file.ts	File contents (text/doc) or base64 image
@"/path with spaces/file.pdf"	Same as above, supports whitespace in paths
@path/to/file.ts#L10-20	Line range syntax preserved in the reference (range applied downstream)
@path/to/dir	Directory listing (files + subdirs, ignores .git/node_modules/build outputs)
@skill:<name>	Loads SKILL.md for a registered skill

@http(s)://... is not treated as a file reference. Unknown namespaces (e.g. @app:erp-prod) are left alone — neither resolved as a skill nor as a file.

Skill resolution

@skill:<name> searches in this order, first hit wins:

1. <cwd>/.pi/skills/<name>/SKILL.md — project-level skill
2. <agentDir>/skills/<name>/SKILL.md — user-level skill (resolved via @amaster.ai/pi-shared's resolveAgentDir(), override with PI_AGENT_HOME)

The order matches loadSkillsFromAllLocations in the pi-coding-agent SDK so a project skill overrides a user-installed one. Frontmatter is stripped; the body is wrapped in <skill name="..." location="...">…</skill> and prepended to the user message.

Output assembly

When at least one mention resolves, the input is rewritten as three optional segments in this order:

<skill name="..." location="...">…</skill>   ← skill blocks (if any)

<original user text with mentions stripped>

<system-reminder>
## file.ts: /abs/path/file.ts
```text
…contents…

Pure-text inputs with no resolvable mentions are left untouched (handler returns undefined).

Configuration

Env var	Default	Meaning
PI_ATTACHMENT_MAX_TEXT_CHARS	128000	Max chars per text/doc attachment before truncation
PI_AGENT_HOME	(from pi-shared)	Override for user-level skill search root

Limits

• Directory listing: capped at 200 entries per directory; remainder is summarized as [Listing truncated: showing 200 of N entries].
• Ignored directory entries: .git, node_modules, .DS_Store, .next, .turbo, dist, build, .cache.
• Mention ordering: skills are matched before files, so the resolved mentions[] array groups by kind rather than preserving textual order. Downstream consumers must not rely on textual order.