Share with a link

Dana has two things to share. New Acme engineers need the acme-skills catalog, and Sam wants to try the code-review stack in all his repositories. She sends a link for each, so the desktop app does the setup for them.

A SkillCatalog link starts with skc:// and opens in the desktop app, which shows what the link would do and asks before it changes anything. Linux has no desktop app, so for a Linux user, send the catalog's Git URL and the entry to add instead.

Share a catalog

For the new engineers, Dana puts this link on the team's onboarding page:

skc://catalog/add?source=git%40github.com%3Aacme%2Facme-skills.git&name=Acme%20Skills

• source is the catalog's Git URL.
• name is the name the confirmation dialog shows.
• Both values are URL-encoded, so @ becomes %40, : becomes %3A, / becomes %2F, and a space becomes %20.

No button in the app makes a catalog link, so you write it yourself, following the link format.

When an engineer opens the link, the app asks whether to add Acme Skills. Choosing Add catalog clones the catalog, as skc catalog add does. Nothing reaches their tools until they choose skills from the catalog.

Share one skill, stack, or bundle

In the desktop app, Dana opens the code-review stack and chooses Share. SkillCatalog checks the stack against Acme's Git host, then shows the link and copies it, with the stack's name as the link text:

skc://share/install?v=1&kind=stack&catalog_id=acme-skills&slug=code-review&source=git%40github.com%3Aacme%2Facme-skills.git

To copy the bare URL instead, choose Copy Raw URL.

Sam installs from the Git host, not from Dana's machine, so SkillCatalog makes a link only when the host has the same files as Dana's clone for the stack and each of its skills. Dana had edited review-checklist by hand, so SkillCatalog first reported:

This item has local changes at <path>. Commit and sync before sharing.

She synced the catalog, then chose Share again:

skc sync --message "Clarify the review checklist"

A sync also fixes the other differences SkillCatalog reports, such as a commit that was never pushed or a newer version that a teammate pushed.

Some items cannot be shared this way. On a review-branch catalog, an item with a waiting proposal can be shared only after the proposal is merged and you have synced, or after you discard it. The Essentials catalog cannot be shared at all, because it comes with the app and has no Git host.

What the recipient sees

Sam opens the link. SkillCatalog first shows only what the link names: the catalog id, the slug, and the Git URL. It reads nothing until he chooses Continue. Then it reads the catalog with Sam's own Git access and shows his choices:

• What you're installing: the stack's name and description.
• Where to install: each of Sam's profiles, marked "Already installed" or "Not installed".
• Create new profile: a new personal profile for a folder that Sam picks.

Sam selects his Home profile and chooses Install. SkillCatalog adds the acme-skills catalog if he does not have it yet, adds the stack to his Home profile, and delivers it.

A project profile appears in the list marked "Project profile". Installing there writes to Sam's local manifest, so the stack reaches only his checkout, and his teammates do not get it.

When SkillCatalog cannot install the stack, for example because Sam's Git access cannot read the repository, it names the problem and changes nothing. If Sam's own clone of acme-skills has changes he has not synced, the install also stops, so he syncs and opens the link again.

What a link cannot do

A link changes nothing by itself. SkillCatalog adds a catalog, changes a profile, or delivers only after the recipient chooses Add catalog or Install.

A link names a skill, stack, or bundle, not a version of it. Sam gets the stack as it is on the Git host when he installs it, and his later syncs update it like any other entry.

A link gives no access. SkillCatalog reads the catalog with the recipient's own Git access, so a private catalog needs an account that can read it.

A link never changes a team manifest. To give a skill to everyone who works in a repository, add it to the repository's team manifest.