Install skills

A skill tells an agent how to carry out one kind of task, step by step, and which rules each step applies. Installing skills with Syllabus gives every checkout of your project the same skills, from the revisions you choose, beside the rules they cite.

Skills come from sources: the repositories your project takes skills and rules from. A source is usually a library, but any Git repository of skill folders works too.

In this guide, you’ll see which skills your sources offer, install a library’s required and recommended skills, and find out where they land. You’ll also install skills from a repository that isn’t a library, resolve a name clash, exclude or fork a skill, write your own, and commit the result.

Start with a project that already has a .syllabus/ directory. If you haven’t created one, follow Set up your first project. To choose rules as well, see Include rules.

Check your skill targets

Syllabus installs a copy of each skill into the folders your agents read. skillTargets in .syllabus/config.yaml names them:

schemaVersion: 2
skillTargets: [claude, agents]

claude installs into .claude/skills/, which Claude Code reads. agents installs into .agents/skills/, which Codex, Cursor, and other agents that follow the shared convention read. syllabus project init writes both, and nothing is written to either folder until the project installs a skill.

To record which skills your sources require before you choose agent folders, set skillTargets: []. Syllabus still records and checks every skill and lists it in .syllabus/generated/SKILLS.md, but writes no installed copies, and sync warns that it installed nothing. See Skill targets.

Add a library

Add your organization’s library as a source:

syllabus project add source fabrica \
  --repository https://github.com/fabricahq/.syllabus.git \
  --skills recommended \
  --non-interactive

This records the source in .syllabus/config.yaml:

sources:
  fabrica:
    repository: https://github.com/fabricahq/.syllabus.git
    skills:
      include: [recommended]

Then sync:

syllabus project sync

What a library’s skills install depends on the level the library sets for each one:

Required skills always install. Even a source with no include at all installs them, now and after every update that adds one.
Recommended skills install because you included recommended.
Offered skills install only when you name them, or include "*" for everything the library offers.

To add an offered skill, name its ID beside recommended:

skills:
  include: [recommended, skills/deploy-preview]

Including a rule group’s rules never installs a skill, and including a skill never includes a rule group’s rules. See Skill selectors.

Sync takes the source’s newest library release, records it in .syllabus/vendor/fabrica/_source.json, and installs every skill from that one release. Later syncs keep that release, even for skills you include later: a skill that isn’t in the recorded release makes sync fail and name syllabus project update fabrica, the command that moves the source. See Update skills.

See what’s available

List every skill your sources offer, with its level:

syllabus project list skills

NAME            ID                                               LEVEL        SET BY             VERSION  STATUS
build-feature   fabrica:skills/build-feature                     recommended  fabrica release 7  1.3.0    installed
deploy-preview  fabrica:skills/deploy-preview                    offered      fabrica release 7  1.0.0    installed
review-change   fabrica:skills/review-change                     offered      fabrica release 7  3.0.0    available
grilling        fabrica:mattpocock:skills/productivity/grilling  offered      fabrica release 7  8a41d07  available
ship-service    fabrica:skills/ship-service                      required     fabrica release 7  1.0.0    installed
tdd             fabrica:skills/tdd                               offered      fabrica release 7  1.1.0    installed
to-spec         fabrica:mattpocock:skills/engineering/to-spec    recommended  fabrica release 7  8a41d07  installed

Each row shows a skill’s install name, its ID, its level and the library release that set it, its version, or a commit for a skill without versions, and whether the project installs it. installed covers skills you included, required skills, and skills another installed skill calls; available means a source offers it and the project doesn’t install it.

The mattpocock: skills are borrowed: Fabrica’s library lists them at a level, but their files come from the original repository, at a commit your project resolves when it updates. See Borrowed skills.

Narrow the list:

--type review lists only review skills, and --type playbook only playbooks.
--applies-rules-from practices/testing lists only skills whose syllabus-rules-used names a rule in that rule group.
--json returns the list for scripts.

See project list skills for every option.

What lands where

After sync, each installed skill appears in several places. Syllabus writes all of them, so don’t edit them by hand:

.claude/skills/build-feature/ and .agents/skills/build-feature/: the installed copies your agents load, one folder per target.
.syllabus/vendor/fabrica/skills/build-feature/: the original files, as the library published that version.
.syllabus/generated/SKILLS.md: one entry per installed skill, with its description, ID and version, level and the library that set it, type, installed paths, how many rules it applies, the skills it calls, and why it’s installed.
.syllabus/generated/installed-skills.json: which folders in the targets Syllabus installed.

An installed copy matches the library’s folder, scripts and their executable bits included, with two additions to SKILL.md:

A marker comment as the first line after the frontmatter, naming the skill’s project ID and version, such as .
When the skill cites rules, a generated section at the end, Rules this skill applies, which links to your project’s version of each rule the skill cites, and a Skills this skill uses line when it calls others.

Don’t edit installed copies: the next sync replaces them, and syllabus project check reports the difference. To change a skill, fork it.

Syllabus writes only the skill folders it installs. Other folders in .claude/skills/ and .agents/skills/, such as a skill another tool installed, stay as they are. When one of them has the name of a skill you install, sync fails with skill-folder-not-managed instead of overwriting it. See Installed skills and Who owns the target folders.

generated/RULES.md gains one line pointing to SKILLS.md, so agents whose tools don’t load skills from the target folders still find them through the instructions in your AGENTS.md.

Skills a skill calls, and the rules it cites

A skill can call other skills and cite rules. When you install it, Syllabus installs those too:

Skills it calls. Every skill in its syllabus-skills-used list, and the skills those call, from the same repository and revision. SKILLS.md says each was installed because another skill uses it.
Rules it cites. Every rule in its syllabus-rules-used list, from the same library, even ones your rule include doesn’t name. These cited rules are reference-only: each gets its generated rule file, and the installed skill links to it, but RULES.md doesn’t list it. Installing a skill never widens the rules your agents apply to all work.

If you exclude or replace a cited rule, the installed skill follows your choice: it links to your replacement, or says the rule is excluded by this project, with your reason. A cited rule your project also includes is an ordinary rule.

When a skill calls another without saying so in syllabus-skills-used, as many third-party skills do, declare the call under skills.uses, so Syllabus installs both:

skills:
  uses:
    skills/architect: [skills/how]

Syllabus doesn’t search skill text for calls it wasn’t told about. See Declare the skills a skill calls.

Install skills from a repository that isn’t a library

Not every useful skill lives in a library. Any Git repository that holds skill folders works as a source, such as a third party’s collection. Add it the same way:

syllabus project add source pstack \
  --repository https://github.com/example/pstack.git \
  --ref main \
  --skills skills/architect \
  --non-interactive

sources:
  pstack:
    repository: https://github.com/example/pstack.git
    ref: main
    skills:
      include: [skills/architect]

Then run syllabus project sync. You don’t declare what kind of source it is: Syllabus finds that the repository has no library manifest, so it’s a non-library source.

Every skill is offered. Nothing installs until you name it, or include "*" for every skill in the repository.
A ref is required. A non-library source has no library releases, so ref must name a branch, tag, or commit. With a branch, sync installs the newest commit on it the first time and records it; later syncs keep that commit, and syllabus project update moves to the branch’s newest commit and shows which skill folders and files changed.
IDs are paths. Each folder with a SKILL.md is a skill, and its ID is the folder’s path in the repository, such as skills/architect.
Expect warnings, not failures. Syllabus checks these skills leniently: where one doesn’t follow the Agent Skills format, sync warns and installs it as it is. A non-library source has no rules or versions, so rules is rejected on it.
Check the license. Syllabus looks for terms in the skill’s license field, then a LICENSE* file in its folder, then LICENSE* and NOTICE* files at the repository root, and records what it finds in provenance. When a skill has none, sync fails with license-not-found; ask the owner to add a license, or stop including the skill.

Syllabus never runs a skill’s scripts. Before you install or update a skill from a repository you don’t control, read its files, scripts included: your agents may run them. To help, the syllabus project update preview flags each new or changed executable script and warns you to read it; see Update skills.

Try a newer version of a borrowed skill

A library chooses the ref it tracks for each repository it borrows skills from, and your project resolves that ref when it updates. To take a borrowed skill from another revision, declare the same repository as your own source, with your own ref:

sources:
  fabrica:
    repository: https://github.com/fabricahq/.syllabus.git
    skills:
      include: [recommended]
  mattpocock:
    repository: https://github.com/mattpocock/skills.git
    ref: v2.0.0

The skills Fabrica borrows from that repository now come from v2.0.0, still at the level Fabrica sets. Repository identity decides the match, not the source name. Remove the source to go back to the library’s ref.

Resolve a name clash

Agents find skills by name, so two installed skills can’t share one. When two sources ship skills with the same name, sync fails with skill-name-clash and writes nothing:

Error: skill-name-clash: fabrica:skills/review-change and pstack:skills/review-change both install as review-change. Rename one with skills.rename, or exclude one. No files were written.

Rename one of them:

sources:
  fabrica:
    repository: https://github.com/fabricahq/.syllabus.git
    skills:
      include: [recommended, skills/review-change]
      rename:
        skills/review-change: fabrica-review

The installed copy is now fabrica-review, in .claude/skills/fabrica-review/. Its ID stays fabrica:skills/review-change. Syllabus doesn’t rewrite the old name where other skills mention it, so every sync that applies the rename warns:

Warning: fabrica:skills/review-change is installed as fabrica-review. Mentions of review-change in skill text aren't rewritten; check the skills that call it by that name.

Check whether any installed skill tells the agent to use review-change. You can rename a required skill too, because it stays installed.

Exclude a skill

Exclude a skill you don’t want, such as one that recommended or "*" brings in, with a reason:

sources:
  fabrica:
    skills:
      include: [recommended]
      exclude:
        - id: skills/write-changelog
          reason: Release Planner writes our release notes.

These are partial snippets, not complete source definitions. An excluded skill isn’t installed, but it stays in vendor/, so updates can show you its changes. When another installed skill calls it, sync warns that the skill it calls isn’t installed.

You can’t exclude or fork a required skill: sync fails and names the library that requires it. Required skills are your organization’s floor; to diverge from one, stop using the source.

You can’t pin a skill to a version either: all of a source’s skills come from one revision and move together when the source updates. To keep a skill as it is, fork it, or set the source’s ref to a library release tag or commit, which holds every rule and skill from that source. See Update skills.

Fork a skill

To change what an included skill says, fork it into your project:

syllabus project add skill \
  --from fabrica:skills/fix-bug \
  --reason 'We use our own bug workflow.' \
  --non-interactive

The command copies the version your project installs into .syllabus/skills/fix-bug/, and adds an exclusion that names the fork:

skills:
  exclude:
    - id: skills/fix-bug
      reason: We use our own bug workflow.
      replacedBy: skills/fix-bug
      basedOn: "1.0.0"

Edit the fork, then run syllabus project build. Agents get your fork in place of the library’s skill. With basedOn, syllabus project update lists the library’s later changes to the skill, so you can decide whether your fork needs them, or replace it with a fork of the newest version with --update-fork fabrica:skills/fix-bug. The library’s license still applies to the copied text. See project add skill.

Write your own skill

Create a skill for this project alone:

syllabus project add skill review-migration \
  --description 'Review a database migration for safety before it merges. Use when a change adds or edits a migration.' \
  --type review \
  --non-interactive

The command writes a draft .syllabus/skills/review-migration/SKILL.md. Authored skills have no versions; they change when you edit them. In syllabus-rules-used, an authored skill cites rules by project ID, such as fabrica:practices/testing/test-behavior-not-implementation or practices/testing/test-project-contracts for one of your own, because it can cite rules from any source. Run syllabus project build to install it. Follow Write a skill for how to write one that works.

Personal skills with the same name

People also install skills for themselves, outside any repository, such as in ~/.claude/skills/. When one of those personal skills has the same name as a skill your project installs, each agent decides which to use, and some use the personal one without saying so. syllabus project sync, update, and check read the known personal skill folders and warn about each pair, naming both paths and what each agent does:

Warning: your personal skill ~/.claude/skills/build-feature has the same name as this project's build-feature (fabrica:skills/build-feature, installed at .claude/skills/build-feature).
  Claude Code uses your personal skill.
  Grok Build reads both, and its docs don't say which it uses.
  VS Code reads both, and its docs don't say which it uses.
Rename or remove your personal skill to use the project's.

Syllabus never writes to your home directory, and the warning doesn’t fail the command. See Personal skills with the same name.

Commit the installed skills

Commit .syllabus/ and the installed skill folders together:

git add .syllabus .claude/skills .agents/skills

Committed copies give every checkout, CI job, and fresh cloud session the same skills without running sync. Run syllabus project check in CI: it fails when an installed copy differs from what sync would write, when a folder Syllabus installed is missing, or when generated/installed-skills.json is out of date.

If your .gitignore excludes a target folder, such as with /.claude/, check reports the folders as missing in every fresh checkout. Add an exception for the skills folder. Git can’t re-include a folder inside an excluded folder, so first change the ignore line to exclude the folder’s contents instead:

/.claude/*
!/.claude/skills/

This keeps ignoring the rest of .claude/, such as local settings, while committing installed skills.

Fabrica SyllabusMIT licensedPrivacy

Built with Fabrica.