Mount layout: ship a `.skills/` directory of query patterns for common agent tasks

[khaliqgant]

Context

Companion to #106 (LAYOUT.md), the filter-view issue, and the digests issue. Even with indexes, filter views, and digests in place, an agent still has to discover the right pattern for a given question on first use. Skills make that discovery explicit and reusable.

Claude Code agents are excellent at reading skill-style markdown — it's how they're trained. Today the agent has to re-derive the optimal query pattern every run; skills mean it reads the recipe once and executes.

Proposal

Ship a .skills/ directory at the mount root with markdown files describing how to compose the mount's primitives for common questions.

~/relayfile-mount/.skills/
├── activity-summary.md      # \"what did I do yesterday/this week\"
├── triage-tickets.md        # \"what should I work on next\"
├── find-by-content.md       # \"find the page/ticket/PR about X\"
├── cross-reference.md       # \"link Linear ticket → PR → Notion spec\"
├── status-report.md         # \"give me a status report on project X\"
└── recent-changes.md        # \"what's changed recently\"

Example: .skills/activity-summary.md

# Activity summary

For \"what did I work on yesterday/this week\" questions:

1. **First, check digests/.** If `digests/yesterday.md` (or `digests/this-week.md`) covers
   the period and the front-matter `generated_at` is recent, just read it.

2. **Otherwise, use filter views — don't grep.**
   - GitHub: `ls github/repos/*/pulls/by-updated/<date>/` + `by-author/<user>/`
   - Linear: `ls linear/issues/by-updated/<date>/`
   - Notion: `ls notion/pages/by-edited/<date>/`

3. **Read the per-item indexes for context.**
   - `github/repos/<owner>/<repo>/_index.json` — repo-level summary
   - `linear/issues/_index.json` — list of all issues with titles/states

4. **Avoid these failure modes:**
   - Don't `find ... -newermt` over the whole tree — use `by-updated/`.
   - Don't `cat` full Notion page bodies for a summary — `by-edited/` filenames are titled.
   - Don't run inline python to parse JSON if `_index.json` already has the field you need.

Why this matters

• Eliminates per-run discovery cost. Without skills, the May 8 benchmark agent burned 5-6 turns sniffing schemas (cat sample.json, ls, etc.). Skills replace that with one file read.
• Encodes the optimal path. Even with all the structural fixes (indexes, filter views, digests), an unguided agent might still try find -newermt. Skills tell it not to.
• Self-improving. Per the persona/skill pattern, skills can be refined based on observed agent runs. Each correction makes future runs cheaper.
• Discoverable. Reference .skills/ from LAYOUT.md so the agent learns about them on first read.

Implementation notes

• Skills are plain markdown — no schema, no MCP layer, no SDK.
• Ship a starter set in v1 (the six listed above); accept community/user-contributed skills later.
• Each skill should:
  • State the problem class it solves
  • Give the optimal sequence of file reads
  • Call out anti-patterns ("don't do X")
  • Reference relevant indexes/views/digests by path
• Skills should be discoverable from the prompt context without the agent having to enumerate them — LAYOUT.md lists what's available.

Predicted benchmark impact

After #106 + filter views + digests:

• Sonnet RF on the May 8 task: ~$0.02-0.05 (one Read of digests/yesterday.md)
• A net-new question without a digest: ~$0.10-0.15 (one Read of the relevant skill, then targeted reads)

Without skills, even with all other fixes, the agent might still wander on the first run of an unfamiliar question class. Skills cap the worst case.

Out of scope

• User-personalized skills — v1 ships a fixed starter set.
• Skill versioning / changelog — markdown frontmatter can carry a version field but no formal contract yet.
• Auto-improvement of skills based on agent trajectories — interesting but separate work.

Relationship to #45 (writes)

relayfile-adapters #45 establishes the file-native write contract (PATCH canonical files, CREATE by draft filename, DELETE canonical). A future skill — .skills/writeback.md — can document those patterns once #45 lands. Out of scope for this issue but worth noting the symmetry: skills cover both reads and writes, all through files.

Acceptance

• Six starter skills exist at .skills/ under the mount.
• LAYOUT.md enumerates and links them.
• Re-running the May 8 benchmark on relayfile (after Mount layout: add indexes, semantic aliases, and a SKILL.md to reduce agent file-shopping #106 + filter views + digests) demonstrates the agent reads the relevant skill on first encounter and uses it.