dotagents

dotagents is a unified CLI for managing agent assets (prompts, skills, configs) from one home source across projects, local agents, and sync workflows.

Features

• Create prompts and skills in a tracked home repo.
• Optionally install newly created assets to project or configured global agent paths.
• Add prompts and skills into the current project quickly.
• Scan agent directories to find unsynced assets.
• Sync skills using a registry-driven workflow.
• Delegate skill package operations to the upstream skills CLI.

Requirements

• Node.js 18+
• npm
• npx skills available for dotagents skill ... passthrough and sync flows

Install

npm i -g @artsnlabs/dotagents

Homebrew (tap):

brew tap moehaje/tap
brew install dotagents

Homebrew one-command install:

brew install moehaje/tap/dotagents

Without global install:

npx @artsnlabs/dotagents --help

Usage

dotagents --help
dotagents create prompt
dotagents add prompt release
dotagents edit prompt release
dotagents add skill terminal-ui
dotagents scan --sync
dotagents config
dotagents skill add vercel-labs/skills@find-skills
dotagents skill sync --check

Command Surface

dotagents create [prompt|skill] [name] [--kind <prompt|skill>] [--name <slug>] [--title <title>] [--description <text>] [--args <text>] [--content <text>|--content-file <path>|--content-stdin] [--home <path>] [--project|-p] [--global|-g] [--agent|-a <name>] [--force]
dotagents add [prompt|skill] [name] [--to <path>] [--agent|-a <codex|claude|agents>] [--all|--select <name,...>] [--home <path>] [--force]
dotagents edit [prompt|skill] [name] [--kind <prompt|skill>] [--name <slug>] [--file <relative/path>] [--inline] [--editor <cmd>] [--home <path>] [--project|-p] [--global|-g] [--agent|-a <name>]
dotagents scan [--home <path>] [--source <path> ...] [--json] [--sync|--sync-all|--sync-select <kind:id:path,...>] [--force]
dotagents config [--home <path> --editor <cmd> --codex <path> --claude <path> --agents <path>]
dotagents skill <skills-cli-args...>
dotagents skill sync [--check] [--yes] [--home <path>]

If dotagents add is run without kind or name in interactive mode, it prompts to select the asset kind and asset(s) from home. dotagents new is kept as a compatibility alias for dotagents create. Use create target flags to control where assets are written: -p (project), -g (global agent homes), -a codex|claude|agents. Combine -p and -a to target agent-local project directories (for example ./.codex or ./.claude). dotagents edit uses the same scope flags and defaults to home scope when no target flags are provided. dotagents edit skill defaults to SKILL.md; pass --file <relative/path> to edit another file in the skill directory. If dotagents edit runs without <name> in interactive mode, it shows a picker of assets found in the selected scope. Use --inline for in-terminal full-content replacement mode (or fallback when no editor can be launched). Use dotagents add --all or dotagents add --select ... to avoid interactive pickers when omitting <name>. Use dotagents scan --sync-all or dotagents scan --sync-select ... for non-interactive sync runs.

Home Repo Resolution

dotagents resolves the home repo in this order:

1. --home <path>
2. DOTAGENTS_HOME
3. Global config (~/.config/dotagents/config.json, or $XDG_CONFIG_HOME/dotagents/config.json)
4. Filesystem auto-detection for dotagents / dot-agents
5. Fallback to ~/dotagents

On first run, dotagents bootstraps global config and initializes a home layout with:

• prompts/
• skills/
• configs/skills-registry.tsv
• scripts/

Project Health

• CI workflow
• Contributing guide
• Security policy
• Code of conduct
• Changelog
• Versioning policy
• Third-party notices

Development

npm install
npm run format:check
npm run lint
npm run type-check
npm run test
npm run build

License

MIT