Skills

AgentSync supports “skills”: small bundles of content, prompts, or helper files that live under .agents/skills/ and can be installed, updated, and managed with the CLI.

This guide explains the expected layout and manifest format, how to install/update skills from providers (for example skills.sh), and troubleshooting tips.

Adopting existing skills (wizard migration)

If you already have skills in agent-specific directories (.claude/skills/, .cursor/skills/, .codex/skills/, .gemini/skills/, .opencode/skills/, .roo/skills/, .factory/skills/, .vibe/skills/, or .agent/skills/), the init wizard will detect and offer to migrate them:

agentsync init --wizard

The wizard:

Detects skill directories across all known agents
Copies skill contents into the canonical .agents/skills/ directory
Handles collisions — if a skill with the same name already exists, it’s skipped with a warning
Preserves originals — optionally backs up source directories

After migration, configure a skills target in agentsync.toml so apply syncs skills back to each agent:

[agents.claude.targets.skills]
source = "skills"
destination = ".claude/skills"
type = "symlink"

Note: Skills migrated via the wizard are NOT registered in registry.json — they’re managed through the symlink pipeline, not the skill install system. Both systems coexist: installed skills live in .agents/skills/ alongside migrated ones.

Choosing `symlink` vs `symlink-contents`

For skills, AgentSync recommends type = "symlink" and uses that as the default in generated config.

symlink keeps one directory link from the agent-specific path back to .agents/skills/.
symlink-contents keeps the destination as a real directory and links each child entry individually.

agentsync init --wizard now makes that choice explicit for each migrated skills target. If the destination already is a correct directory symlink to .agents/skills, the wizard recommends symlink and keeps that as the default so an existing healthy layout is preserved.

If you intentionally override to symlink-contents, the wizard prints a post-init validation warning before exit. You can also detect the same mismatch later with agentsync doctor, and agentsync status will show a focused hint while still treating the destination as healthy.

Directory structure

AgentSync keeps installable skills under the project .agents/skills/ directory. Each installed skill has its own subdirectory and a registry.json file tracks installed skills.

Example layout (after installing one skill):

.agents/
└── skills/
    ├── my-skill/
    │   ├── SKILL.md
    │   └── other-files...
    └── registry.json

The registry is used by the CLI to return metadata when --json is requested and to track versions and installed files.

SKILL.md manifest

Skills must include a SKILL.md file with YAML frontmatter describing the skill. At minimum the manifest must provide name and may include version and description.

Example SKILL.md (minimal):

---
name: my-skill
version: 1.0.0
description: A short description of this skill.
---

# Usage

Prompts and examples...

Validation rules

name must match the following regular expression (enforced by the manifest parser):
```
^[a-z0-9]+(-[a-z0-9]+)*$
```
This means:
- One or more lowercase letters or digits, optionally followed by groups of a single dash and one or more lowercase letters or digits.
- Examples: weather-skill, my2-skill, a.
- Disallowed: uppercase letters, spaces, leading/trailing dashes, consecutive dashes (e.g., bad--name).
version is optional, but if present must be valid semver.

If parsing fails, the CLI will return a validation error indicating the problem.

CLI: install, update, list

AgentSync exposes skill management via agentsync skill subcommands.

Install a skill (from a provider id, local archive, or directory):

agentsync skill install my-skill --source https://example.com/my-skill.zip

Update a skill to the latest/source provided:

agentsync skill update my-skill

List installed skills (structured JSON output is planned for future releases):

agentsync skill list

Flags:

--source — optional. Use a local path, archive URL, or provider-specific identifier.
--json — output machine-readable JSON with skill metadata from .agents/skills/registry.json.

Providers and sources

AgentSync supports installing skills from multiple providers (for example skills.sh) as well as local archives or directories. The install logic accepts ZIP/tar archives or local paths.

See specs/001-skills-sh-integration for the ongoing skills.sh integration work: https://github.com/dallay/agentsync/blob/main/specs/001-skills-sh-integration/README.md

Errors & remediation

Common error hints the CLI prints (derived from implementation):

manifest errors: “Check the SKILL.md syntax, frontmatter, and ensure the ‘name’ field matches requirements.” — occurs when frontmatter is missing or invalid.
network / download / HTTP errors: “Check your network connection and ensure the skill source URL is correct.”
archive errors: “Verify the skill archive is a valid zip or tar.gz. Try re-downloading or using a fresh archive.”
registry errors: “There was a problem updating the registry. Ensure you have write access and the registry file isn’t corrupted.”

When an install/update fails, re-run with higher verbosity or use --json to get structured error output.

Security & safe usage

The CLI validates skill identifiers and rejects path traversal (no / or \ and no absolute paths). This protects projects from accidental overwrites. The validation is implemented in the CLI: see src/commands/skill.rs (function validate_skill_id).
Treat third-party skill archives as untrusted input. Review the contents before installing in sensitive environments.

Links & further reading

Manifest parser (source): https://github.com/dallay/agentsync/blob/main/src/skills/manifest.rs
CLI skill command implementation: https://github.com/dallay/agentsync/blob/main/src/commands/skill.rs
Skills spec (work in progress): https://github.com/dallay/agentsync/blob/main/specs/001-skills-sh-integration/README.md