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

Bucketed (auto-detected when skills/ groups skills under top-level buckets — often dot-prefixed), e.g. openai/skills:

my-skills-repo/
└── skills/
    ├── .curated/
    │   └── gh-fix-ci/
    │       └── SKILL.md
    └── .system/
        └── skill-creator/
            └── SKILL.md

Skill id is the innermost folder name (gh-fix-ci), so the symlink stays flat (~/.cursor/skills/gh-fix-ci). On id collisions across buckets, .curated wins over .experimental over other buckets over .system.

Only immediate child directories that contain SKILL.md are treated as skills. Detection order is nested → bucketed → flat; the detected layout is shown as a badge on each repository card.

Codex plugin metadata

When a skill directory contains agents/openai.yaml (openai/skills convention), ide-agents reads its interface block for presentation only:

YAML field	Shown in UI
display_name	Card title (falls back to name)
short_description	Description (falls back to SKILL.md, then metadata.short-description)
default_prompt	"Suggested prompt" block
icon_large / icon_small	Reserved for future icon rendering

This file is not an ide-agents agent — it is metadata for the skill and is never installed as a separate agents/<name>.md.

SKILL.md frontmatter

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

scope values

Value	UI behavior
global	Only Global toggle enabled
project	Only Project toggle enabled
any	Both toggles available (independent)
(missing)	Same as any

Agents

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

---
name: my-agent
description: When to delegate to this subagent.
scope: any
skills:
  - related-skill
subagents:        # router agents only
  - other-agent
---

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.

Router agents

subagents is only for router agents that delegate to other agents. When a router is installed, ide-agents transitively enables the delegated agents (recursively, with cycle protection) along with their own skills. A subagent cannot be turned off while a router that depends on it stays installed in the same scope; on uninstall, ide-agents offers to remove the delegated subagents and their now-unused skills. Leaf agents list only their own skills and never use subagents.

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.