Skills

Enable, compose, and generate native agent skills at the right scope.

agentsmith treats a skill as a source directory containing SKILL.md and optional support files. It generates that directory into each harness’s native skill root.

Enablement

For a scope, enabled skills are the ordered union of:

1. skills enabled by selected packs, in pack order;
2. skills_enable entries on the profile or scope;
3. minus skills_disable entries at that same scope.

A pack that enables skills declares them in its optional pack.toml:

skills = ["to-issues", "address-review"]

Instruction-only packs and packs that only contribute skill slots need no manifest.

A scope can adjust the result:

skills_enable = ["release-notes"]
skills_disable = ["address-review"]

An exclusion only affects skills introduced by that scope. It cannot hide a skill inherited from an ancestor.

Skill sources

skills/to-issues/
├── SKILL.md
├── references/
│   └── conventions.md
└── scripts/
    └── create.ts

SKILL.md needs Agent Skills front matter with name and description. The public name must match the source directory basename.

Every Markdown file is rendered through the same include-and-slot pipeline. This means directives inside Markdown support files are rendered too. It does not make include paths relative to the support file.

All includes use the same source-root lookup as directives in SKILL.md:

<!-- agentsmith:include skills/severity-guidance.md -->

During project generation, an unqualified include first checks:

<project>/.config/agentsmith/partials/skills/severity-guidance.md

then falls back to:

<shared-source-repository>/partials/skills/severity-guidance.md

A qualifier can require the project-owned include:

<!-- agentsmith:include project:skills/severity-guidance.md -->

It resolves to:

<project>/.config/agentsmith/partials/skills/severity-guidance.md

Moving a Markdown support file within its skill directory therefore does not change how its includes resolve. Non-Markdown support files are copied byte-for-byte and retain executable mode.

Composable skills

A skill can declare slots, and selected packs can provide reusable content for those slots:

packs/github/skill-slots/tracker/10-github.md
packs/github/skill-slots/harnesses/claude-code/tracker/20-claude.md

Contributions are keyed by slot name, not skill name. The same tracker snippet is inserted into every enabled skill that declares a tracker slot. A project-owned pack can therefore supply one project’s tracker instructions to any number of shared skills without knowing their names.

This produces flat, self-contained skills tailored to the selected packs and harness—no runtime skill chaining is required.

Collision protection

agentsmith fails when two visible sources would emit the same public skill name or when a planned skill collides with an unmanaged visible skill. Use asmith project explain to see where a skill was enabled and lint to detect collisions before writing.

For a complete source-to-output example, continue with Create a composable skill.