GitHub linked code
Keep a skill's or plugin's code in a GitHub repository: connect the repository, link a folder, see which skills a change upstream affects, publish it after review, and move a plugin to GitHub and back.
Your team may already keep scripts, templates and other code in GitHub. Instead of copying those files into Symbol, you can link a folder of a GitHub repository into a skill's files or a plugin's files. GitHub stays the place where the code is edited. Symbol reads the folder, shows the files read-only, tells you which skills rely on a file that changed, and delivers the code to installers only after someone reviews and publishes it.
This is different from listing a plugin from another repository, where installers fetch the whole plugin from the repository themselves. With linked code, the plugin is still built and published in Symbol, and installers get it from Symbol.
Connect a repository
Open the Marketplace settings of the workspace (your personal Settings → Marketplace, or an organization's Settings → Marketplace) and find the GitHub repositories card.
- Choose Connect a repository. Symbol sends you to GitHub to sign in and approve the Symbol GitHub App.
- Back in Symbol, the card says Connect as your GitHub login and lists the repositories you can pick: only the ones GitHub confirms you are an admin of, in the Symbol app's installations. If the list is empty, install the app on the repository first, or ask one of its admins to connect it.
- Pick a repository and choose Connect repository.
Symbol reads connected repositories with read-only access and never writes to them. A connection request must be finished within 10 minutes, and can be used once. In each workspace, Symbol remembers the GitHub account you first connected with, and later connections you make there must use the same account.
Each connected repository shows its status: Connected, Access revoked or Unreachable, with the reason when it stopped working, and how many linked folders use it. A workspace can connect up to 20 repositories.
If the card says GitHub is not set up on this server, connecting is not available there yet.
Link a folder
Linking a folder needs a connected repository. Where you start depends on what the code is for:
- For one skill: open the skill, and in its Files section find Linked from GitHub.
- For a whole plugin: in Marketplace settings, open the plugin's Linked code section.
Choose Link files from GitHub and fill in:
- Repository: one of the connected repositories.
- Folder in the repository: for example
plugin/scripts. Leave it blank for the whole repository. - Read from: a branch or a tag, and its name.
- Folder in the skill or Folder in the plugin: where the files appear, for
example
scripts. Leave it blank for the top folder.
Then choose Link folder. A skill or a plugin can link up to 10 folders. A linked folder cannot overlap another linked folder, or files already stored in Symbol under the same folder. For a plugin you can replace those stored files instead: see Replace a plugin's stored files.
What you see
Each linked folder lists its repository and folder, the branch or tag, where its files land, the commit Symbol last accepted (with a link to that commit on GitHub), how many files it holds and how many were left out, and when it was last checked. Its status is Up to date, Checking, Out of date or Not read.
Linked files appear in the file tree with the other files and are marked as linked from GitHub. Opening one shows the repository, folder, branch or tag and commit it came from, and Open in GitHub opens it at that exact commit. Linked files are read-only in Symbol: change them in the repository. You also cannot add a stored file inside a linked folder.
What is left out
Symbol reads every file in the folder, and never runs any of them. Some entries are left out and counted:
- files that look like they hold secrets, such as
.envfiles, private keys and credentials files, - dependency folders such as
node_modulesor.venv, and version control folders such as.git, - operating system files such as
.DS_Store, - symbolic links and submodules,
- files larger than 1 MiB, the limit for one file,
- paths a skill or plugin does not accept.
Some problems stop the whole folder from being read, and the folder keeps its last good copy:
- two files in the folder would land on the same path,
- a file would replace one Symbol writes for the plugin,
- the folder has more than 10,000 entries,
- the files do not fit the skill's or plugin's size or file count limits (see the limits for skill files and plugin files).
The folder then shows Not read or Out of date, with the reason. Fix it in the repository and refresh.
When Symbol reads the folder again
Symbol reads a linked folder again:
- when you open the skill's or plugin's files, unless it was checked in the last minute,
- when you choose Refresh now on the folder,
- before every publish,
- in the background, for every folder that has gone six hours without a check.
Each read uses exactly one commit of the branch or tag. If a read fails, the last good copy stays in use and the folder says why.
Skills that rely on linked files
When a linked file changes upstream, the skills that rely on it are flagged, the same way dependency review flags a capsule whose link changed. The skill says how many linked files it relies on changed in GitHub, and you can filter lists to Linked code changed.
What counts as relying on a file
A skill relies on a linked file when its instructions name it:
- they run or import it, for example
python scripts/check.py, - they mention it, for example in a link, in a code span, or as
${CLAUDE_PLUGIN_ROOT}/shared/config.jsonfor a plugin's file.
A skill can reach the linked files of its own folders and of its plugin. When a script
builds a path while it runs, declare it so Symbol knows about it, in a front matter
block at the top of the skill or in a comment anywhere in it. A path ending in /
covers every linked file under that folder:
---
symbol-depends:
- scripts/helpers/
- data/rates.csv
---
<!-- symbol-depends: templates/report.md -->Starting to rely on a file does not flag the skill. It is flagged when something changes after that: a file it relies on is added, deleted, renamed, changed, or has its permissions changed.
When you open a linked file among a plugin's files, Used by lists the skills that load, declare or mention it. Skills you cannot open are counted, not named.
What the review shows
The skill names each changed file and how it changed, grouped by repository and folder, and lists the commits between the version it last approved and the current one, when GitHub can answer. If the branch history was rewritten, so the older commit is no longer part of it, the review says so: check the files themselves.
Clearing it
There are three ways:
- Still works: confirm the skill still works with the changed files.
- Edit the skill: edit it from the review, and saving it confirms the files too.
- Publish: a publish approves the linked files it ships, as that release has them. Publishing the skill clears its own linked folders. Files in a plugin's linked folder clear when you publish the plugin, since installers get them with the plugin. A change that arrives while you publish stays flagged.
Confirming needs edit access to the skill, and no GitHub account. Open the full skill first: a list or a preview cannot confirm. A confirmation counts only for exactly the changes you were shown, works once, and expires after 24 hours. If the folder changed again while you were reviewing, the newer change stays flagged and Symbol asks you to load the latest version. Confirming clears only the linked files, not the skill's other reasons to be stale.
If you turned dependency review off for your account, you do not see linked code changes either.
Publishing linked code
Linked files are part of the skill's or plugin's draft. Nothing reaches installers until a version is published, through the same review as any other code: see Publishing code.
A publish reads every linked folder again first. The review then names each linked folder that changed since the release installers have: the commits between, with their title, author and date, and every file that was added, removed, changed, renamed or had its mode changed.
Symbol refuses the publish, and installers keep the current release, when:
- a linked repository was disconnected or its access was revoked,
- GitHub could not be reached,
- a linked folder's last read failed,
- a newer read of a folder has not finished yet,
- a folder changed after you opened the review. Review the newest changes and confirm again.
Publishing copies the linked files into the release. Installers get them from Symbol, so they need no access to GitHub, and installing never reads GitHub. Earlier releases keep their own copies, so you can still roll back to one after its commits are deleted or rewritten upstream.
Unlink a folder
Choose Unlink on the folder and pick what happens to its files:
- Keep the files in Symbol: the files stay exactly as they are now, with their executable setting, as stored files you can edit in Symbol. Changes on GitHub no longer reach them.
- Remove the files: the files are removed from the draft. Their history stays.
Either way, installers keep the version they have until the next publish, which you review first. To link the folder again later, link it as a new folder.
Your account export includes each linked folder's source and the copy of its files Symbol keeps, but not the repository's history, which stays on GitHub.
Replace a plugin's stored files with a linked folder
When a plugin already stores files under a folder and the same files now live in GitHub, you can switch that folder to the repository. In the plugin's Link files from GitHub form, choose Replace stored files with this folder. This is offered for a plugin's files, not for a single skill's.
Symbol reads the folder and compares it with the stored files, against one commit:
- Different in the repository: use the repository's version, or use it and keep
the Symbol copy in
kept-from-symbol/. - Only in Symbol: remove it, or keep it in
kept-from-symbol/. - Only in the repository, Identical, and Not linked (left out, with the reason) are listed for you to check.
Every different file and every file only in Symbol needs a choice before Link files is available. If anything changed since the preview, Symbol says so and shows the new comparison. The plugin keeps its name, its history and its skills' names. Installers keep what they have until the next reviewed publish.
When access stops
Disconnecting a repository in the GitHub repositories card asks first. Its linked folders keep their last copy, marked out of date, and can no longer be read. A skill or plugin that uses them cannot be published until you unlink those folders, keeping or removing the files, and link them again from a connected repository if you still want them.
If the Symbol GitHub App is removed from the repository, or GitHub stops showing the repository, the connection shows Access revoked or Unreachable with the reason, and publishing waits in the same way.
Move a plugin back to GitHub
A plugin built in Symbol can move to a marketplace in one of your connected repositories. In Marketplace settings, choose Move back to GitHub on the plugin.
- Pick the Destination repository, an existing Branch (a tag cannot be the base of a pull request), and the Marketplace folder in the repository, or leave it empty for the top level. To start a new marketplace, choose an empty folder and tick Start a new marketplace in this empty folder.
- Choose Preview. Symbol shows the repository, its visibility, the commit the change is based on, the plugin's folder, every file the change writes, whether it is executable and whether it is added, changed, removed or unchanged, and, for a new marketplace, the manifest it writes.
- Fix anything listed under Fix these before exporting, such as a mention that cannot be packaged or a path the repository already uses for something else.
The change holds every skill as a standalone SKILL.md, with each mention turned
into a relative link to a packaged file, the capsules those skills mention as
reference files, the plugin's agents, its stored files, and every linked folder from
its accepted copy. Other files and plugins in the repository are kept.
Permission to release
Everything in the change must be allowed to go to that repository at its current visibility. Under the preview, each item that is not yet allowed has Allow release to this repository:
- A capsule you do not own is allowed by its owner.
- A linked folder from another repository is allowed by the person who connected that repository as its admin.
Reading, confirming or installing something does not allow its release. If the repository later becomes visible to more people than the permission covered, the export is refused until it is allowed again.
Open a pull request, or submit it yourself
- Open a pull request from Symbol: available once you are an admin of the destination repository on GitHub and have chosen Authorize writing to approve the Symbol writer app, with write access to contents and pull requests. Symbol opens one pull request. Merging it is up to your team.
- Download a Git bundle and open the pull request yourself: always available.
Download the bundle, then run the command Symbol shows in a clone of the repository.
It uses Git and the GitHub CLI (
gh) with your own GitHub credentials.
If the branch moved, or the plugin or a permission changed since the preview, Symbol asks you to preview again.
Switch installers
Symbol keeps serving the plugin until your team removes it. After the pull request is merged, the export shows the commands that move installers to the GitHub marketplace, for Claude Code and for Codex. Plugin and skill names stay the same. For a marketplace at the top of the repository's default branch, the Claude Code commands look like this:
/plugin marketplace remove <old-marketplace-name>
/plugin marketplace add <owner>/<repo>For another branch or folder, the commands clone the repository first.
Return an exported plugin
A plugin you moved to GitHub can come back to Symbol, including the edits your team made there. In Marketplace settings, choose Return an exported plugin and give the repository, the branch, the marketplace folder and the plugin's name as people install it. This works for a plugin exported with Move back to GitHub, and for a marketplace you downloaded or cloned from its Export section and committed to a connected repository.
Choose Preview to see every skill, reference, agent and file and what happens to it:
- If the plugin is still in Symbol, its records keep their history. Edits made only in the repository become new versions, edits made only in Symbol are kept, and a file edited on both sides needs a decision: Keep the repository version, Keep the Symbol version or Skip.
- If it was deleted from Symbol, the plugin is rebuilt from the repository. Everything is created new, and deleted history is not brought back.
A downloaded or cloned marketplace replaces each reference to other workspace content with "[reference omitted from this export]". A skill like that never takes the repository copy on its own: when it changed, was renamed or was deleted in the repository, it needs a decision. Keep the Symbol version and Skip leave the text and its references as they are, and the next edit in the repository asks again. Replace it with the repository copy asks you to confirm first, then makes the repository text, placeholders included, the current version; the previous version stays in its history. For a deleted file the same choice removes the skill from the plugin.
Symbol recognizes the export only from your own workspace. A copy returned into another workspace, or one whose export file was moved or edited, comes back as new records. If the repository holds more than one export file for the plugin, choose the one to read.
Links that point nowhere, and paths claimed twice, are listed before anything is written: fix them in the repository and preview again. If the repository or the Symbol copy changes after the preview, Symbol asks you to preview again.
The plugin comes back as a draft. Installers keep the current version until the returned draft is reviewed and published.
To take the whole marketplace with you instead, as a ZIP or as a read-only URL your CI clones, see Export your marketplace.
To bring in a whole marketplace repository at once, including plugins that were never in Symbol, see Import a marketplace repository.
Your AI assistant
Over MCP and through Symbol Bridge, your AI reads linked
files with read_skill_file, like any other skill file. A full read of a skill
whose linked files changed lists them under its stale reasons and, when you can edit
the skill, includes a receipt. Your AI confirms with that receipt through
confirm_capsule_validity, or passes it to update_capsule so the edit confirms the
files. Through the Bridge, that read is answered by Symbol online, because only Symbol
can issue the receipt.
Who can do what
- Connect and disconnect repositories: the personal marketplace's owner, or an organization owner or Admin, signed in on the web. They also need to be an admin of the repository on GitHub. Other members see no connected repositories.
- Link, refresh, unlink and replace stored files: the personal owner, or an organization owner or Admin. On a skill, they also need edit access to it. Organization API keys cannot.
- Publish linked code: the same people who can publish code.
- See which skills use a plugin's linked file: the people who manage the plugin. They see only the skills they can open by name.
- Confirm a skill still works: anyone with edit access to the skill, with no GitHub account needed.
- Move a plugin to GitHub and return it: the personal owner, or an organization owner or Admin. Opening the pull request from Symbol also needs you to be an admin of the destination repository who has authorized writing.
Limits
| Limit | Value |
|---|---|
| Connected repositories per workspace | 20 |
| Linked folders per skill or plugin | 10 |
| Entries in one linked folder | 10,000 |
| One linked file | 1 MiB |
| Folder path in the repository | 1,024 bytes |
| Branch or tag name | 255 characters |
| Time to finish connecting | 10 minutes |
| A confirmation receipt | once, within 24 hours |
Linked files also count toward the skill's or plugin's own file count and size limits.