Skip to main content

Source repositories

ide-agents connects to any git repository with a predictable layout. Corporate or private skill catalogs live in separate repos — ide-agents only clones and links them.

Expected layout​

Nested (default):

my-skills-repo/
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── agents/              # optional
    └── my-agent.md

Flat (auto-detected when skills/ is missing or contains no skill folders with SKILL.md), e.g. bluriesophos/cursorskills:

my-skills-repo/
├── code-review/
│   └── SKILL.md
├── debug-to-fix/
│   └── SKILL.md
└── agents/              # optional
    └── my-agent.md

Only immediate child directories that contain SKILL.md are treated as skills.

SKILL.md frontmatter​

---
name: my-skill
description: What this skill does.
scope: any
---

scope values​

ValueUI behavior
globalOnly Global toggle enabled
projectOnly Project toggle enabled
anyBoth toggles available (independent)
(missing)Same as any

Agents​

Agent files are agents/<name>.md. Optional YAML frontmatter with description, scope (same values as skills), and skills (block list of skill ids the agent depends on).

When an agent lists skills, ide-agents auto-installs those skills with the same scope (Global or Project) and blocks removing an installed skill while a dependent agent remains installed.

Adding a repository​

  1. Open Repositories in the UI (/repositories)
  2. Pick a suggested catalog or enter a git URL and branch (default main)
  3. Click Add / Clone

Enable target IDEs under Settings (/settings) before installing skills or agents.

Local testing​

Use a file:// URL:

file:///absolute/path/to/repo

Private repositories​

Configure SSH or gh authentication yourself. ide-agents does not store tokens.

Empty repository bootstrap​

If the clone has no installable artifacts (empty repo or only GitHub init files such as README.md / .gitignore), ide-agents automatically copies a starter template from the npm package:

  • Demo skill hello and agent oracle
  • Example .cursor/rules/, .claude/CLAUDE.md, .agents/AGENTS.md

After clone, the UI shows how many skills and agents were added and whether the bootstrap was pushed to the remote.

For a repo that was cloned before bootstrap existed (or bootstrap was skipped), expand the repo card on Repositories and click Add starter template. The repo must still be empty — non-empty catalogs return an error.

See REST API for the POST /api/repos/:id/bootstrap endpoint.

Installing artifacts​

  1. Open Skills or Agents
  2. Select a repository
  3. Click Global (🌐) or Project (📁) on a card

Symlinks are applied immediately. Click the active icon again to remove the symlink.