Skip to content
AgentSync

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)

Section titled “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:

Terminal window
npx @dallay/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.

Section titled “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

Section titled “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

Section titled “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

Section titled “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 for installation, but required for the skill update command to work (must be valid semver).

Version requirement for updates

Section titled “Version requirement for updates”

When updating a skill with agentsync skill update <SKILL_ID>, the SKILL.md manifest must contain a valid version field in the frontmatter. Without it, the update will fail with the error “missing version in SKILL.md”.

Example with version:

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


# Usage


Prompts and examples...

If you don’t intend to update a skill, the version field can be omitted from the manifest.

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

CLI: suggest, install, update, list

Section titled “CLI: suggest, install, update, list”

AgentSync exposes skill management via agentsync skill subcommands.

  • Suggest repository-aware skills without modifying .agents/skills/:
Terminal window
npx @dallay/agentsync skill suggest
Terminal window
npx @dallay/agentsync skill suggest --json
Terminal window
npx @dallay/agentsync skill suggest --install
Terminal window
npx @dallay/agentsync skill suggest --install --all

agentsync skill suggest is repository-aware, but still conservative:

  • it detects repository technologies from local files using a data-driven catalog engine
  • it maps those detections to AgentSync’s curated recommendations
  • it reports already-installed skills instead of hiding them
  • it stays read-only unless you explicitly opt into install mode

What skill suggest does

Section titled “What skill suggest does”

The default suggest flow is read-only. It:

  1. scans the current repository for technology markers defined in the catalog
  2. reports the detected technologies and their confidence
  3. looks up recommended skills from AgentSync’s catalog
  4. marks whether each recommendation is already installed in .agents/skills/registry.json

This is intentionally opinionated and curated by AgentSync. It is not a general package detector and it does not try to recommend every possible skill for every tool it sees.

Supported repository technology detection (current scope)

Section titled “Supported repository technology detection (current scope)”

AgentSync supports detection for 110+ technologies. Detection rules are defined in the catalog and include config file existence, package dependencies, and file extensions.

A representative set of supported technologies and markers includes:

Technology idHuman labelRepresentative local markers
rustRustCargo.toml
node_typescriptNode/TypeScriptpackage.json, tsconfig.json
astroAstroastro.config.*, package.json (astro)
reactReactpackage.json (react, react-dom)
nextjsNext.jsnext.config.*, package.json (next)
vueVuepackage.json (vue)
svelteSveltesvelte.config.js, package.json (svelte)
pythonPythonpyproject.toml, uv.lock, poetry.lock, requirements*.txt
github_actionsGitHub Actions.github/workflows/*.yml, .github/workflows/*.yaml
dockerDockerDockerfile*, compose.yml, docker-compose*.yml
postgresqlPostgreSQLpackage.json (pg, postgres, @vercel/postgres)
eslintESLinteslint.config.*, .eslintrc.*
prettierPrettier.prettierrc.*, prettier.config.*
vitestVitestvitest.config.*, package.json (vitest)
playwrightPlaywrightplaywright.config.*, package.json (playwright)
makeMakeMakefile, GNUmakefile

Notes:

  • Detection uses repository contents only; recommendation metadata does not decide what technologies are detected.
  • Root-level canonical markers yield high confidence.
  • Nested markers generally yield medium confidence.
  • Markers under test/example-style paths yield low confidence.
  • AgentSync ignores common generated/vendor directories like .git, .agents, node_modules, target, dist, build, .astro, .next, .turbo, and .pnpm-store while scanning.

Recommendation metadata now comes from a hybrid catalog model:

  • AgentSync ships an embedded declarative catalog in the binary, so skill suggest still works offline and always has a baseline recommendation source.
  • Providers may expose an optional catalog overlay. Valid provider entries extend or override matching embedded entries by stable ids.
  • Invalid provider entries are ignored individually; if provider metadata is missing, unreadable, or invalid at the top level, AgentSync falls back to the embedded catalog.
  • A single technology can recommend multiple skills. For example, the embedded catalog currently maps astro to frontend-design, accessibility, performance, core-web-vitals, and seo, and maps github_actions to both github-actions and pinned-tag.
  • The schema also supports explicit combo entries (multi-technology recommendations). Those entries are loaded and preserved now, but active combo evaluation is currently deferred.

Compatibility bridge: canonical ids vs current runtime ids

Section titled “Compatibility bridge: canonical ids vs current runtime ids”

The catalog model separates two identities:

  • provider_skill_id: the canonical id used in catalog metadata
  • local_skill_id: the current local/runtime id used by today’s CLI and install system

That compatibility bridge matters because current runtime behavior still uses local slug ids:

  • agentsync skill suggest emits skill_id values using the local/runtime id
  • agentsync skill install <SKILL_ID> still expects a single path-safe slug, not a slash-delimited canonical provider id
  • installed skills still live at .agents/skills/<skill_id>/
  • installed-state lookup still keys off the local/runtime id in registry.json

In other words: catalog metadata can be more future-facing than the runtime contract, but the current user-facing CLI behavior remains stable.

Read-only output and JSON

Section titled “Read-only output and JSON”

Human output shows detections, recommended skills, reasons, and install state. --json returns the stable machine-readable contract with detections, recommendations, and summary.

Example read-only flow:

Terminal window
npx @dallay/agentsync skill suggest

Example JSON flow:

Terminal window
npx @dallay/agentsync skill suggest --json

Phase 2 adds recommendation-driven installs:

  • agentsync skill suggest --install opens an interactive multi-select prompt in a TTY and only offers recommended skills that are not already installed.
  • agentsync skill suggest --install --all is the non-interactive path and installs every recommended skill that is still pending.
  • Already installed recommendations are still shown in read-only output, but install flows skip them instead of reinstalling them.
  • If you run --install without a TTY, AgentSync fails safely and tells you to use --install --all.

Example interactive install:

Terminal window
npx @dallay/agentsync skill suggest --install

Example non-interactive install-all:

Terminal window
npx @dallay/agentsync skill suggest --install --all
  • Install a skill (from a provider id, local archive, or directory):
Terminal window
npx @dallay/agentsync skill install my-skill --source https://example.com/my-skill.zip
  • Update a skill to the latest/source provided:
Terminal window
npx @dallay/agentsync skill update my-skill
  • List installed skills (structured JSON output is planned for future releases):
Terminal window
npx @dallay/agentsync skill list

Flags:

  • --source — optional for skill install and skill update. Use a local path, archive URL, or provider-specific identifier.
  • --json — output machine-readable JSON. For skill suggest, this is the detections/recommendations/summary contract shown below.

Example skill suggest --json response:

{
  "detections": [
    {
      "technology": "rust",
      "confidence": "high",
      "evidence": ["Cargo.toml"]
    }
  ],
  "recommendations": [
    {
      "skill_id": "rust-async-patterns",
      "matched_technologies": ["rust"],
      "reasons": [
        "Recommended because Rust was detected from Cargo.toml."
      ],
      "installed": false
    }
  ],
  "summary": {
    "detected_count": 1,
    "recommended_count": 1,
    "installable_count": 1
  }
}

Example skill suggest --install --all --json response:

{
  "detections": [
    {
      "technology": "rust",
      "confidence": "high",
      "evidence": ["Cargo.toml"]
    }
  ],
  "recommendations": [
    {
      "skill_id": "rust-async-patterns",
      "matched_technologies": ["rust"],
      "reasons": [
        "Recommended because Rust was detected from Cargo.toml."
      ],
      "installed": false
    }
  ],
  "summary": {
    "detected_count": 1,
    "recommended_count": 1,
    "installable_count": 1
  },
  "mode": "install_all",
  "selected_skill_ids": ["rust-async-patterns"],
  "results": [
    {
      "skill_id": "rust-async-patterns",
      "status": "installed"
    }
  ]
}

Example: how future catalog additions fit the model

Section titled “Example: how future catalog additions fit the model”

Detection support for a new technology is still a Rust change first. For example, adding support for a new technology (say, solidjs) would typically require:

  1. adding a new Rust TechnologyId and detector markers
  2. adding a catalog skill definition and technology entry
  3. optionally adding combo entries later

A catalog entry could look like this:

[[skills]]
provider_skill_id = "example/skills/solidjs"
local_skill_id = "solidjs"
title = "SolidJS"
summary = "Build reactive UIs with SolidJS patterns."


[[technologies]]
id = "solidjs"
name = "SolidJS"
skills = ["example/skills/solidjs"]


[technologies.detect]
packages = ["solid-js"]

That TOML shape is already supported by the catalog model. But the repository would not start detecting the technology until the Rust detector also learned how to report its id.

Skill sources: owned vs external

Section titled “Skill sources: owned vs external”

AgentSync resolves skills from two kinds of sources:

dallay-owned skills (dallay/agents-skills)

Section titled “dallay-owned skills (dallay/agents-skills)”

The dallay/agents-skills repository is the canonical home for all skills maintained by the AgentSync team. These include accessibility, docker-expert, github-actions, rust-async-patterns, and more. For the full, up-to-date list of skills, see the repository.

When you install a dallay-owned skill, the CLI resolves it deterministically — it constructs the download URL directly from the catalog entry without making any search API call:

agentsync skill install docker-expert
→ resolves to: dallay/agents-skills/docker-expert
→ downloads: https://github.com/dallay/agents-skills/archive/HEAD.zip#skills/docker-expert

In this URL, the #skills/docker-expert fragment identifies the skills/docker-expert subdirectory inside the downloaded ZIP archive, so the CLI can extract and install just that skill directory.

This means installs are fast, reliable, and work even when external search APIs are unavailable.

Want to contribute a skill? See the CONTRIBUTING.md in the agents-skills repo for the skill directory structure, manifest format, quality expectations, and PR process.

External provider skills

Section titled “External provider skills”

Skills maintained by external organizations (Angular, Vercel, Cloudflare, Expo, Stripe, etc.) are resolved from their respective GitHub repositories. These follow the same owner/repo/skill-name pattern:

agentsync skill install angular-developer
→ resolves to: angular/skills/angular-developer
→ downloads: https://github.com/angular/skills/archive/HEAD.zip#skills/angular-developer

For skill IDs that don’t match the owner/repo/skill-name pattern (simple IDs), AgentSync falls back to the skills.sh search API after first checking the catalog.

Providers and sources

Section titled “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

Section titled “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

Section titled “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 logic lives in src/skills/catalog.rs (function validate_local_skill_id), which is invoked by the CLI.
  • Treat third-party skill archives as untrusted input. Review the contents before installing in sensitive environments.

Links & further reading

Section titled “Links & further reading”