Building Context Packs · GitHub Copilot Best Practices

Key insight: OpenCode is only as good as the context you give it. Two people asking the same question will get very different results — the one with well-organised, relevant files in their session will get specific, accurate, actionable output. The one without will get generic answers.

What is a context pack?

A context pack is simply a curated folder of files that you give OpenCode access to so it understands your specific world — your team, your processes, your projects, your history. Rather than explaining everything from scratch in every prompt, you let the files do that work.

It can include anything: playbooks, process documents, project transcripts, meeting notes, org charts, past deliverables, Confluence exports, email threads, role descriptions — whatever is relevant to the task at hand.

What types of files work

OpenCode can read a wide range of file types directly:

PDF — great for playbooks, reports, exported Confluence pages
Word / DOCX — process documents, written guides
PowerPoint / PPTX — presentations and decks (OpenCode reads the text content)
Plain text / Markdown — notes, transcripts, AGENTS.md files — these are ideal as they're lightweight and fast to read
CSV / Excel — data, trackers, lists
Meeting transcripts — exported meeting transcripts are excellent context for summarisation, action item extraction, and follow-up tasks

Tip: Plain text and Markdown files are the most reliable format. If you have a choice, export or save as text. For PDFs and Word docs, OpenCode reads them well but very large files can slow things down — split them if they're over ~50 pages.

How OpenCode loads context

There are three ways context gets into a session — and understanding the difference matters:

1. Files in your working folder (automatic)

When you open OpenCode in a folder, it's aware of everything in that folder. It won't read every file upfront, but it knows they're there and will pull them in when relevant. This is the baseline — put the right files in the right folder before you start a session.

2. Referencing a file explicitly with @

You can point OpenCode directly at a specific file mid-session by typing @ followed by the filename. This is useful when you want to make sure a particular document is read, rather than hoping OpenCode picks it up on its own. In the Desktop app, @ opens a fuzzy file search.

3. Via MCP / API (live context)

For content that changes regularly — Confluence pages, Jira tickets, Webex messages — connecting via MCP means OpenCode always has the current version, rather than a static export you remembered to download last week. See MCPs / APIs for Context (Read) for how to set this up.

Should I use a local folder or something better?

A local working folder is fine to get started, but it has real limitations as your usage grows:

Files only exist on one machine — if you switch devices or a colleague wants to use the same context, it doesn't work
No version history — if you overwrite a file you can't get it back
Not shareable — teammates have to maintain their own copies

The better pattern is to store your context files in a GitHub repository (synced locally), so they're versioned, accessible from any machine, and shareable with the team. OneDrive works for sharing but doesn't give you version history or the ability to collaborate properly.

See File Management for the recommended folder structure and setup.

Naming and organising your files

OpenCode uses filenames as part of its understanding — a well-named file gives it immediate context before it even reads the content.

Be descriptive: CX-Ops-Release-Mgmt-Playbook-v3.pdf not doc_final2.pdf
Include dates or versions: Team-Org-Chart-May2026.docx — so OpenCode knows which is most current if you have multiple versions
One topic per file: a focused 5-page document beats a 50-page mega-doc for context quality
Group by project or task: keep context files for a specific project together in a subfolder so you're not loading irrelevant files into every session

A practical folder structure

OpenCode/
├── Context/
│   ├── Org/
│   │   ├── CX-Ops-Team-Overview.md
│   │   └── My-Role-Description.md
│   ├── Processes/
│   │   ├── Release-Mgmt-Playbook.pdf
│   │   └── Change-Control-Process.pdf
│   └── Transcripts/
│       └── CX-Ops-Standup-2026-05-01.txt
├── Project-A/
│   ├── AGENTS.md
│   ├── brief.md
│   └── [project-specific context files]
└── Project-B/
    ├── AGENTS.md
    └── [project-specific context files]

The Context/ folder holds reusable background files you'll want across many sessions. Project folders hold task-specific files. When you start a session on Project A, OpenCode has everything it needs in that folder — plus you can reference the shared context files with @ when needed.

The AGENTS.md file

When you run /init in a folder, OpenCode creates an AGENTS.md file. This is a special context file that tells OpenCode about the project — what it is, how to approach tasks, any rules or preferences. You can edit it manually to add your own instructions that persist across every session in that folder.

Think of it as a standing brief you write once and never have to repeat in prompts again.