Skill

Preview

Skill support isn’t in a released version of Syllabus yet. This page describes how it will work.

A skill is the AI skill you already know, officially a folder that follows the open Agent Skills standard. It holds a SKILL.md file that tells an agent how to carry out one kind of task, plus any scripts, references, or assets it bundles.

Skills are coarse-grained. A skill that builds a feature combines many practices, from where the code lives to how it’s tested and verified, and not all of them apply every time. That makes skills good for playbooks, techniques, and coordinating a whole task, but clumsy as the only way to deliver guidance: you can’t adopt, update, or version one practice inside a skill on its own.

Rules are the granular layer: one best practice per file, with its own version. A skill cites the rules it applies, so each practice is written once, and every skill that applies it stays current.

Syllabus installs skills into your repository, records where each one came from and which version it is, and checks them. It doesn’t run skills, decide when an agent uses one, or check that the agent followed it.

What a skill contains

A skill uses the standard format from the Agent Skills specification: a folder named after the skill, holding a SKILL.md file and any scripts, references, or assets it bundles.

build-feature/
  SKILL.md
  references/
    slicing.md
  scripts/
    verify.sh

SKILL.md starts with YAML frontmatter, followed by the instructions. The standard requires two fields: name, which agents find the skill by, and description, which agents read to decide when to use it.

Syllabus extends the format with three keys of its own, under the standard’s metadata field:

---
name: build-feature
description: Build a feature from an agreed spec, one slice at a time. Use when starting implementation of a new feature or a change to an existing one.
metadata:
  syllabus-skill-type: playbook
  syllabus-rules-used: |
    practices/testing/test-behavior-not-implementation
    practices/verification/verify-on-the-surface-users-touch
  syllabus-skills-used: |
    skills/tdd
---

1. Read the spec and name the slice you're building.
2. Decide where the code lives before writing it.
...

• syllabus-skill-type labels what kind of skill it is, playbook or review. See Skill types.
• syllabus-rules-used lists the rules the skill applies. Syllabus takes those rules with the skill, and the installed copy links to your project’s version of each one. See Where cited rules live.
• syllabus-skills-used lists other skills the skill calls. Syllabus installs them alongside it.

All three keys are optional. The standard sets metadata aside for properties it doesn’t define, so a skill with these keys is still a standard skill, and agents that don’t read them use it as usual. For every field and check, see Skill format. To write one, follow Write a skill.

Skill types

A skill type classifies what a skill is for, so skills are easier to search and browse. You can already filter by type, such as syllabus project list skills --type review. The full payoff comes from interfaces that show types, such as a catalog like Rulemart that lets you browse every review skill across libraries.

There are probably many useful kinds of skills, but we’re conservative about which types we name, because removing or redefining a type later would break the skills that use it. For now there are two, and a skill can declare one:

Type	What the skill does	Examples
playbook	Ordered steps for carrying out one kind of engineering task, citing the rules each step applies.	Build a feature, fix a bug, migrate a dependency
review	Examines existing work, such as a diff, plan, test suite, or rendered UI, against stated criteria and reports findings.	Review a pull request, audit a test suite

The test is the skill’s main job: a playbook changes the work, and a review judges work that already exists. A review may offer to fix what it found, and a playbook may include a review step.

If a skill doesn’t clearly fit either type, leave the type out. The type is only a label: Syllabus installs, checks, and updates typed and untyped skills the same way.

Where cited rules live

A skill cites rules from its own repository, so the rules it depends on always travel with it:

• A library’s skill cites only rules in the same library, by their ID there, such as practices/testing/test-behavior-not-implementation. Any project that installs the skill from that library gets those rules too, at the same release.
• A skill you author in your project can cite your project’s own rules, and also rules from the project’s sources by project ID, such as fabrica:practices/testing/test-behavior-not-implementation.
• A skill from a repository that isn’t a library has no rules to cite, so Syllabus ignores its syllabus-rules-used.

In a library, syllabus library check fails when a skill cites a rule that doesn’t exist or was retired, so a typo never reaches an agent. See Rules a skill applies.

Skills and rules

Keep each practice in a rule, and cite it from the skills that apply it. When a skill needs a practice followed, it cites the rule rather than restating it:

• A project can exclude or replace the rule, and every skill that cites it picks up the project’s choice.
• When the rule gets a new version, every skill that cites it applies the new version, without a change to the skill.
• Reviewers check work against the same rules the implementing agent followed.

Skills don’t belong to rule groups, and including a rule group’s rules never installs a skill. When you install a skill, Syllabus also takes the rules it cites, even ones your rule include doesn’t name. These cited rules are for reference: the skill links to them, but they don’t join RULES.md, so installing a skill never widens the rules that apply to all of your project’s work.

Where skills come from

A repository gets skills from three places:

• Libraries. A library publishes the skills in its .syllabus/skills/ folder, and can list skills it borrows from other repositories. It sets a level for each one; see Skill levels.
• Non-library sources. Any Git repository with skill folders and no library manifest, such as a third party’s skill collection. Every skill in it is offered. Because it has no library releases, its ref names a branch, tag, or commit, and Syllabus records the exact commit.
• Your repository. Skills you author live in .syllabus/skills/.

When a skill calls others, Syllabus installs them alongside it, from the same repository and revision.

A skill’s ID is its folder’s path in the repository that holds it, such as skills/build-feature. Its identity is that repository plus that path, so two sources that reach the same repository name the same skill. In a project, an ID is qualified by the source name you chose, such as fabrica:skills/build-feature. Configuration uses these IDs to include, exclude, rename, and replace skills.

A project can exclude a source’s skill it doesn’t want, with a reason, or fork it into an authored skill that installs in its place under the same name. Updates list the source’s later changes to a skill the project forked, so the project can decide whether its fork needs them.

See Install skills to add skills to a project.

Skill levels

A library sets a level for each skill it publishes, saying how strongly it asks its projects to install it:

Level	What a project that uses the library gets
Required	Always installed, whatever the project’s include says. The project can’t exclude or fork it.
Recommended	Installed when the project includes recommended.
Offered	Installed when the project names it, or includes "*".

A library’s own skill that no level lists is offered, so a library lists only the skills it has an opinion about. An organization can make some skills the floor for every project by requiring them in its org library: a project that takes anything from that library installs them. A project sees only the levels of the libraries it names; levels don’t chain through a library’s own sources.

A library can also list skills from another repository at a level, such as a third party’s skill its teams should use. Projects fetch those borrowed skills from the original repository, at a commit each project resolves when it updates, and record which library required, recommended, or offered them. See Borrowed skills.

Names, renames, and clashes

Agents find skills by name, so the folder an installed skill goes in is named after its install name, which is its own name unless your project renames it. Two installed skills can’t share a name. When two sources ship skills with the same name, rename one of them in configuration; sync fails until no clash remains. A rename changes only the installed name: it doesn’t rewrite the old name where other skills mention it, and every sync that applies one warns about that. See Rename a skill.

A person can also install personal skills outside any repository, which their agents load in every repository. When a personal skill has the same name as a skill your repository installs, each agent decides which one to use: Claude Code uses the personal skill, Codex shows both, and Grok Build and VS Code read both without documenting which they use. Syllabus never writes to your home directory; it warns when it finds such a pair. See Personal skills with the same name.

Skill decisions layer in this order, each overriding the ones before it: a library, an org library, the project, then each person’s personal skills. Required skills are a floor the project can’t remove.

How a skill is versioned

A library skill has its own semantic version, which covers its whole folder and follows the same levels as a rule’s:

• Major: the skill now produces or requires something different, such as a removed or reordered step that people rely on, a new required input, or a new rule or skill it uses.
• Minor: the skill adds steps or guidance without breaking how it was used.
• Patch: the skill only clarifies its wording.

Library authors record each change in a change note, and a library release publishes the new versions. Unlike rules, a project doesn’t choose skill versions or pin skills: all of a source’s skills come from one revision, the library release or commit the project recorded for that source, so skills that call each other always match. A skill’s version tells you what changed. Projects see it in their generated files and in the syllabus project update preview, and every installed skill moves when its source updates. To hold a skill back, exclude it, fork it, or set the source’s ref, which holds everything from that source. Authored skills and skills from non-library sources have no versions.

See Rule and skill versions for the details.

How agents use installed skills

When you sync, Syllabus writes a copy of each installed skill into the folders your agents read: .claude/skills/ for Claude Code and .agents/skills/ for Codex, Cursor, and other agents that follow the shared convention. You commit these copies, so every checkout and every fresh cloud session has the same skills.

When a skill cites rules, its installed SKILL.md ends with a generated section, Rules this skill applies, that points at your project’s version of every rule the skill cites, including any authored rule that replaces one. Agents read those rules in full before the step that uses them.

Syllabus also writes .syllabus/generated/SKILLS.md, which lists every installed skill, its source, level, and version, how many rules it applies, and the skills it calls. Agents in tools without native skill support can read it there.

When a skill and a rule disagree, agents should follow the rule and report the conflict, so someone can fix the skill. See For agents.