# Skills, Context & Library

Orb and sandboxed.sh provide two complementary ways to give agents domain knowledge, files, and tools:

1. **Project Context & Project Skills**: Synchronized per-project files (`@context`) and skills (`skills/<name>/SKILL.md`) managed directly in Orb and Finder.
2. **The Global Library**: A Git-backed repository of reusable workspace templates, global skills, rules, commands, agents, and MCP server definitions.

---

## 1. Shared Project Context (`@context`)

Every project has a writable **Context** directory synchronized across Core, remote fleet nodes, and your Mac (`~/.orb/project-context/<server>/<account>/<project>`):

- **Reference in prompts**: Type `@context`, `@context/notes.md`, or `@"context/research notes.md"`. Unlike one-off file attachments, `@context` resolves directly to the live synchronized directory on the execution host (mounted at `/run/sandboxed-context/<project>` inside Linux containers).
- **Bidirectional sync & conflict resolution**: Edits made by an agent, in Orb's Markdown editor (`⌘/`), or in macOS Finder sync every two seconds with SHA-256 blob verification and version history (up to 10 MiB per file, 100 MiB per project). If concurrent edits conflict, Orb preserves both variants so you can compare and resolve them.

## 2. Project Skills (`skills/<name>/SKILL.md`)

Put project-specific skills inside the project's synchronized files under `skills/<name>/SKILL.md` (with optional supporting files alongside them):

```markdown
---
name: review
description: Review a proposed change using the project checklist.
---
Read references/checklist.md before reviewing the change.
```

All missions in that project automatically inherit its skills. Before launching or resuming a turn, Orb / Core / `sandboxed-node` links or stages the project skills into the harness's native discovery path:

| Harness | Native Project Discovery Path |
| --- | --- |
| **Codex** | `.agents/skills/<name>` |
| **Claude Code** | `.claude/skills/<name>` |
| **Antigravity (`agy`)** | `.agents/skills/<name>` |
| **OpenCode** | `.opencode/skills/<name>` |
| **Grok** | `.grok/skills/<name>` |

---

## 3. The Git-Backed Library

The **Library** (`~/.sandboxed-sh/library`, configured via `LIBRARY_REMOTE`) is a Git repository for global, version-controlled configuration across all projects:

```text
library/
├── skill/              # Global skills (<name>/SKILL.md)
├── command/            # Slash commands
├── rule/               # Global behavioral rules
├── agent/              # Agent profiles
├── mcp/                # MCP server definitions
└── workspace-template/ # Container blueprints (distro, init_script, skills, env_vars)
```

### MCP Security & Allowlists

Workspace-scoped stdio MCP servers defined in the Library are launched via a mission-local `0700` wrapper script. The wrapper clears inherited environment variables and passes only:
- The MCP server's own configured `env` map
- Workspace environment variables explicitly listed in `workspace_env_allowlist`

Secret values never appear in generated harness config files (`opencode.json`, `.claude/settings.local.json`, `.codex/config.toml`) or process arguments.