agnes

Vendor-agnostic agent configuration for the AI coding era.

One core source of truth:

| Core file | Role | Standard | |-----------|------|----------| | AGENTS.md | Ambient project guidance | agents.md (AAIF / Linux Foundation) | | agents/skills/*/SKILL.md | Invokable workflows | Agent Skills | | agents/mcp.json | Tool connections (no secrets) | MCP |

Thin adapters project that core into each vendor’s discovery paths:

.claude/skills · .agents/skills · .cursor/skills · .grok/skills · …

          edit once
              │
              ▼
     ┌────────────────┐
     │  agents/skills │  AGENTS.md  agents/mcp.json
     └───────┬────────┘
             │  agnes sync
     ┌───────┴────────┬────────────┬──────────┐
     ▼                ▼            ▼          ▼
 Claude Code       Codex        Cursor       Grok
 .claude/skills  .agents/…   .cursor/…   .grok/…

Install

# global CLI (binary name: agnes)
npm install -g agnes-sync

# or one-shot
npx agnes-sync init
# after global install:
agnes init

From this repo (development):

npm install
npm run build
npm link          # puts `agnes` on your PATH

Quick start

cd your-project
agnes init              # scaffold core + sync adapters
agnes skill new deploy  # add a portable skill
agnes validate
agnes sync
agnes status

Edit only:

• AGENTS.md
• agents/skills/**
• agents/mcp.json
• agnes.yaml (which adapters / symlink vs copy)

Then re-run agnes sync after skill changes (symlinks usually need no re-sync).

Commands

| Command | Purpose | |---------|---------| | agnes init | Create core layout + agnes.yaml + sync | | agnes sync | Skills + shells + MCP → vendor paths | | agnes validate | Check skills against agentskills.io rules | | agnes status | Show core vs adapter wiring (--global for ~) | | agnes skill new <name> | Scaffold a skill package | | agnes skill list | List core skills | | agnes import <from> | Pull skills from a vendor path into core | | agnes adapters | List known vendor adapters | | agnes mcp sync | Project agents/mcp.json → vendor MCP files | | agnes mcp status | Catalog + projected MCP targets | | agnes mcp enable | Set mcp.sync: true in agnes.yaml |

Useful flags

agnes init --adapter claude-code cursor codex --method symlink
agnes init --dry-run            # print every write, change nothing
agnes sync --force              # replace non-empty vendor dirs
agnes sync --dry-run
agnes sync --global             # also link ~/.claude/skills etc.
agnes sync --no-mcp             # skills only
agnes mcp sync --strict-secrets # fail if catalog has raw secrets
agnes import claude-code        # from .claude/skills → agents/skills
agnes validate --strict
agnes validate --json           # machine-readable report for CI
agnes status --global

MCP projection

Edit only agents/mcp.json (JSONC — // comments allowed). Prefer ${ENV} placeholders.

agnes sync (when mcp.sync: true) or agnes mcp sync writes:

| Target | Path | Format | |--------|------|--------| | Claude / standard | .mcp.json | { "mcpServers": … } | | Cursor | .cursor/mcp.json | same | | VS Code / Copilot | .vscode/mcp.json | { "servers": … } | | Grok | .grok/config.toml | managed [mcp_servers.*] block | | Codex | agents/mcp.codex.toml | TOML fragment to merge into Codex config |

Secret-like values (Bearer tokens, sk-…, long hex) are warned on sync; use --strict-secrets in CI.

Config (agnes.yaml)

version: 1
core:
  skills: agents/skills
  agentsMd: AGENTS.md
  mcp: agents/mcp.json
adapters:
  - universal      # .agents/skills (shared by many tools)
  - claude-code    # .claude/skills + CLAUDE.md shell
  - codex
  - cursor
  - grok
  - gemini-cli
method: symlink    # or copy — `agnes init` defaults to copy on Windows,
                   # since committed symlinks do not survive a Windows clone
shells:
  claude: true
  gemini: false
mcp:
  sync: true
  targets:
    - mcp-json
    - cursor
    - vscode
    - grok
    - codex-fragment

Why not only npx skills?

npx skills is excellent for installing skills from catalogs into agent folders.

agnes is complementary: it owns the project’s single source of truth and keeps vendor trees as projections (plus AGENTS.md shells and import/validate). Use both:

# third-party skill into core, then project out
npx skills add some/repo --skill foo   # may land in a vendor path
agnes import .claude/skills --force    # fold into agents/skills
agnes sync

Or author skills only under agents/skills/ and never touch vendor dirs.

Skill format

agents/skills/my-skill/
├── SKILL.md          # required
├── scripts/          # optional portable executables
└── references/       # optional on-demand docs

---
name: my-skill
description: >-
  What it does and when to use it (keywords for discovery).
---

# My Skill

Portable steps. Prefer scripts/ and MCP over harness-specific APIs.

Design rules (portability)

1. Core is editable; adapters are not (except via agnes import).
2. No secrets in git — MCP catalog uses ${ENV} placeholders only.
3. No model lock-in in skills — model choice is runtime policy.
4. Scripts beat proprietary tools — a scripts/verify.sh runs everywhere.

Development

npm install
npm run build
npm test
node dist/cli.js --help

Release

Publishing is automated: push a v* tag and GitHub Actions runs .github/workflows/publish.yml (typecheck → test → build → npm publish) via npm trusted publishing. (Provenance is omitted while the GitHub repo is private — npm requires a public source repo for Sigstore provenance.)

npm version patch           # or minor / major
git push origin main --follow-tags

The tag must match package.json (v0.3.2 ↔ "0.3.2"). Full checklist: agents/skills/release-check/. One-time: configure the Trusted Publisher on npm for ketok-id/agnes → workflow publish.yml.

License

MIT