# For Agents

Use this guide when an AI agent is installing, reviewing, editing, or
publishing the public Endor Labs Agent Kit distribution repo.

## Decide The Job

| User Intent | Work In | Do Not Start By Editing |
| --- | --- | --- |
| Install a host package | `README.md`, then `plugins/<host>/endor-labs-agent-kit/README.md` | Generated package internals |
| Install the Cursor package | `.cursor-plugin/`, root `agents/`, root `skills/`, root `hooks/`, and `assets/logo.png` | Gemini extension files |
| Run Cursor SDK automation | `cursor-sdk/README.md` | Cursor IDE plugin metadata or Gemini extension files |
| Install the legacy Claude package | `plugins/claude/ai-plugins/README.md` | Marketplace ids or generated agents |
| Review or validate distribution artifacts | `docs/plugin-release-checklist.md` and package READMEs | Source recipes that live in another repo |
| Change agent behavior | [🐙 The Endor Labs Agent Kit](https://github.com/endorlabs/endor-labs-agent-kit/tree/main) `source/agents/` | This repo's generated `plugins/` tree |
| Change generated docs or package shape | [🐙 The Endor Labs Agent Kit](https://github.com/endorlabs/endor-labs-agent-kit/tree/main) `src/endor_agent_kit/publication/` | Hand-edited generated package READMEs |
| Propose a new agent, skill, hook, or action contract | [🐙 The Endor Labs Agent Kit](https://github.com/endorlabs/endor-labs-agent-kit/tree/main) `docs/contributing-agents.md` | This repo |
| Sync a release candidate | `docs/distribution-sync.md` | Partial copied package files |

## Source Boundary

This repository is the public distribution mirror. The source of truth for
Agent Kit behavior is
[🐙 The Endor Labs Agent Kit](https://github.com/endorlabs/endor-labs-agent-kit/tree/main).

Generated provider packages under `plugins/` should come from Agent Kit
publication output. Do not rewrite generated prompts, skills, agents, package
READMEs, or manifest files here to change behavior. Change the source repo,
regenerate, sync, and compare.

New agents, skills, hooks, and action contracts must be proposed in Agent Kit.
After a maintainer merges the source PR, Agent Kit automation opens the
generated distribution PR here.

The Cursor package is now source-generated by Agent Kit. Sync `.cursor-plugin/`,
generated root workflow `agents/`, generated root workflow `skills/`, and
generated root advisory `hooks/`, and `assets/logo.png` from the source repo.
Sync `cursor-sdk/` for Python SDK automation. Root `.mcp.json` and root
`GEMINI.md` are support context, not Cursor package output or an installable
Gemini extension. The repo root must not contain `gemini-extension.json`.

## Install Without Drift

When installing or copying artifacts:

1. Read the root `README.md` and the selected package README.
2. Copy generated directories exactly.
3. Keep sibling files such as `actions.yaml`, `architecture.svg`,
   `agent.manifest.json`, `output-contract.md`, and `endorctl-setup.md` when a
   package includes them.
4. Do not summarize, merge, or rewrite generated prompt bodies.
5. Report missing Endor auth, namespace, `gh`, MCP, `endorctl`, host CLI, or
   runtime prerequisites before live Endor work.

## Edit Safely

Before editing generated package directories, confirm whether the change belongs
in the Agent Kit source repo. Normal package updates use:

```bash
AGENT_KIT_REPO="/path/to/endor-labs-agent-kit"

python3 "$AGENT_KIT_REPO/scripts/sync_ai_plugins_distribution.py" \
  --source "$AGENT_KIT_REPO" \
  --target .
diff -qr "$AGENT_KIT_REPO/plugins" ./plugins
```

Run local mirror validation before claiming the sync is clean:

```bash
AGENT_KIT_REPO="/path/to/endor-labs-agent-kit"

for skill in skills/*; do python3 scripts/quick_validate.py "$skill"; done
python3 -m json.tool .claude-plugin/marketplace.json >/dev/null
python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
python3 -m json.tool .cursor-plugin/marketplace.json >/dev/null
python3 -m json.tool .cursor-plugin/plugin.json >/dev/null
python3 -m json.tool cursor-sdk/agent_definitions.json >/dev/null
python3 -m json.tool hooks/hooks.json >/dev/null
python3 -m json.tool plugins/claude/endor-labs-agent-kit/hooks/hooks.json >/dev/null
python3 -m json.tool plugins/codex/endor-labs-agent-kit/hooks/hooks.json >/dev/null
python3 -m json.tool plugins/gemini/endor-labs-agent-kit/hooks/hooks.json >/dev/null
python3 -m json.tool plugins/antigravity/endor-labs-agent-kit/hooks.json >/dev/null
test ! -e plugins/claude/ai-plugins/hooks
for hook_script in hooks/*.sh plugins/*/*/hooks/*.sh; do bash -n "$hook_script"; done
python3 - <<'PY'
import py_compile

py_compile.compile("cursor-sdk/run_cursor_agent.py", cfile="/tmp/run_cursor_agent.pyc", doraise=True)
PY
python3 -m json.tool .mcp.json >/dev/null
test -f GEMINI.md
test ! -e gemini-extension.json
test -f plugins/gemini/endor-labs-agent-kit/gemini-extension.json
test ! -e plugins/gemini/endor-labs-agent-kit.zip
diff -qr "$AGENT_KIT_REPO/.cursor-plugin" ./.cursor-plugin
diff -qr "$AGENT_KIT_REPO/agents" ./agents
diff -qr "$AGENT_KIT_REPO/cursor-sdk" ./cursor-sdk
diff -qr "$AGENT_KIT_REPO/hooks" ./hooks
for skill in "$AGENT_KIT_REPO"/skills/*; do
  name=${skill##*/}
  [ "$name" = "create-endor-labs-agent" ] && continue
  diff -qr "$skill" "./skills/$name"
done
diff -q "$AGENT_KIT_REPO/assets/logo.png" assets/logo.png
git diff --check
```

## Approval Gates

Ask before stale, destructive, credentialed, or external-write actions:

- branch push
- PR/MR creation
- public package release
- host marketplace writes
- install or uninstall commands in a user's real host profile
- live `endorctl api` lookups
- Endor auth, namespace, integration, scan profile, exception-policy, or
  package-manager changes

Setup workflows must not run scans, run `endorctl host-check`, auto-install
tools, edit shell profiles, configure global MCP, or write credentials without
explicit approval.

## Public Package Rules

- New Claude Code users should prefer `endor-labs-agent-kit@endorlabs`.
- Existing Claude Code users may keep `ai-plugins@endorlabs`.
- Do not enable both Claude package ids in the same profile for normal use.
- Gemini distribution is directory/GitHub based. Do not create or publish
  `plugins/gemini/endor-labs-agent-kit.zip`.
- Do not couple Cursor package sync to Gemini CLI extension files.
- Provider install behavior can drift. Re-check live provider docs and host CLI
  behavior before release.