Skip to main content

​
What a linked repository is

It is a GitHub repo that the workspace takes its skills from. Skills are written and reviewed in the repo, and after each merge into the linked branch, what is new or changed reaches Tuqui on its own. They are not edited in Tuqui: in Settings → Skills each one says “From” and the name of the repo, and to change it you go to the repo. It only covers workspace skills, not personal ones. If a personal skill has the same name as one from the repo, the repo skill hides it. Repos are managed on a page that hangs from Skills: in Settings → Skills, click Manage repositories and Repositories opens. To go back, use ← Skills. It is not in the Settings menu, and only workspace admins see the button.

​
Repository format

Each skill is a folder with a SKILL.md in the Agent Skills format, directly inside the linked folder (skills/ by default). The other files in the folder travel with the skill.
The frontmatter of SKILL.md carries metadata.id:
metadata.id is required and must not change: lowercase with hyphens, up to 64 characters. Tuqui uses it to recognize the skill. With the same id you can rename the skill or move it to another folder, and it is still the same skill. Two folders with the same id make both fail. A skill that does not follow the format or goes over a limit does not arrive: the last valid version stays, and the error shows on the repo screen.

​
Status of a repository skill

Under each linked repo you see the branch, the folder, the last commit and the time of the last sync, and a table with the status of each skill: What a merge brings arrives in less than 5 minutes. If the GitHub notice gets lost, it still arrives within 15 minutes. To skip the wait, click Sync now. Each change that arrives goes into the skill’s version history, with its commit.

​
Install the Tuqui GitHub App

Tuqui reads repos with its own GitHub App. It only asks for read access to the contents of the repos you pick: it does not write to GitHub. Before you start: you must be a workspace admin. An owner of the GitHub organization installs the App; if you are not one, GitHub sends the request to one.
  1. Go to Settings → Skills, click Manage repositories and then Connect GitHub.
  2. On GitHub, pick the organization and the repos Tuqui can read.
  3. Confirm. GitHub sends you back to Tuqui.
Result: the GitHub account shows on the screen and you can link a repo. If GitHub sent the request to an owner, click Connect GitHub again once they approve it. The GitHub menu of the page lists the accounts with the App installed. To add or remove repos, or to install the App on another organization, click Manage on GitHub: GitHub opens, and when you come back the new account is linked. If the App was installed directly from GitHub, use Search installations on GitHub. If the App was already installed from GitHub, you do not need to install it again.
  1. Click I already installed it from GitHub. If an account is already linked, use the GitHub → Search installations on GitHub menu.
  2. GitHub asks you to authorize Tuqui with your user and sends you back to Tuqui.
  3. If your GitHub user owns only one new account with the App, it is linked right away. If it owns more than one, Tuqui shows them all checked: uncheck the ones you don’t want in this workspace and click Link the selected ones.
Result: the accounts you picked show in the GitHub menu. Workspace admins can link repos from those accounts, so link only the ones that belong to this workspace. Only an owner of the account on GitHub can link it.

​
Disconnect GitHub from this workspace

  1. Open the GitHub menu and click Disconnect GitHub from this workspace, at the end of the menu.
  2. The confirmation says how many repos are unlinked and how many skills stop arriving. Confirm with Disconnect.
Result: every GitHub account of the workspace is unlinked, all its repos are unlinked and their skills stop arriving, without being deleted. The screen goes back to Connect GitHub. The App stays installed on GitHub and other workspaces do not change. To remove Tuqui’s access in every workspace, uninstall the App on GitHub: the confirmation has one link per account. Before you start: the App must be installed on the repo. Protect the branch you are going to link on GitHub: anyone who can merge into it publishes skills to the workspace, including scripts.
  1. Click Link repository.
  2. Pick the Repository. The Branch is filled in with the main branch of the repo; change it if the skills are on another one.
  3. In Folder, keep skills/ or type the folder that holds the skills.
  4. Read the warnings and click Link.
Result: the repo shows in the list and its skills arrive with the first sync. Workspace skills with the same name as one in the repo start to come from the repo and show as Adopted. They keep who they were shared with, the agents that use them and their history. The same happens if the repo later adds a skill with the name of one that was already in the workspace.
  1. Open the repo’s ⋯ menu and click Unlink. Sync now is in the same menu.
  2. The confirmation says how many skills stop arriving. Confirm with Unlink.
Result: those skills stop arriving, without being deleted. If you link the repo again, the same skills come back. To move skills from one repo to another, link the new one before you unlink the old one. Skills with the same metadata.id move to the new repo and never stop arriving.

​
Duplicate a repository skill to edit it

If you need your own version of a skill that comes from the repo, make a copy.
  1. In Settings → Skills, open the skill menu and pick Duplicate and edit.
  2. Type a New name and click Create copy.
Result: the copy is a workspace skill of its own, with the files beside SKILL.md. You can edit it, and it no longer updates from the repo.

​
Troubleshooting

​
Skills says “There are problems in” a linked repository

A repo could not sync or has skills that failed. The warning shows above the list in Settings → Skills, and only admins see it. Click View repositories and look for the repo with the error.

​
The repo says “Not synced since” a time

GitHub did not answer, the App lost access to the repo, or the linked folder has no skill. In the meantime, Tuqui does not delete or retire anything. Read the reason under the warning. If the App lost access, add the repo again with GitHub → Manage on GitHub. Then click Sync now.

​
A skill says “Failed”

The error in the table says what is wrong: invalid frontmatter, a missing or repeated metadata.id, or a file over a limit. Fix it in the repo and merge. Until then, the last valid version stays in use. The App has no access to that repo. Click Your repo is not here? Give the app access on GitHub, add it and open Link repository again.