AGENTS.md

Guidance for AI coding agents working in this repository. CLAUDE.md is a symlink to this file.

What this repo is

Elastic's Microsoft 365 Copilot Cowork plugin (elastic/copilot-cowork-plugin): Elastic platform agent skills (cloud, elasticsearch, kibana) plus the Elastic Docs MCP server, packaged as an M365 app (Unified App Manifest v1.29). It is the Cowork counterpart of elastic/claude-plugin. See README.md for the full picture.

Key constraints

• Do not edit files under skills/. They are synced from elastic/agent-skills and local edits are overwritten. Fix skills upstream.
• Do not edit appPackage/skills/ or the agentSkills array in appPackage/manifest.json. Both are generated by npm run build. All other manifest fields are hand-maintained.
• Shipping is opt-in. Only skills named in INCLUDED_SKILLS (scripts/build-package.ts) are packaged. Cowork caps a plugin at 20 skills and 10 connectors; the tests enforce both.
• Do not bump version in manifest.json by hand. The Release workflow owns it. It must be 1.0.0 or higher (Microsoft's validator rejects a leading 0).
• Do not run atk commands that sign in or touch an M365 tenant (atk auth login, atk install, atk provision, atk publish, atk validate --package-file) unless a human asks. Offline commands (atk validate --manifest-file, atk package) are fine.

Commands

Requires Node.js 24+ and the atk CLI (npm install -g @microsoft/m365agentstoolkit-cli).

npm install
npm run build     # flatten allow-listed skills into appPackage/skills/ + regenerate agentSkills
npm run lint      # ESLint + Prettier check
npm test          # Jest: build script + package invariants (runs build first)
npm run package   # build + offline atk validate + zip -> appPackage/build/appPackage.dev.zip

Code style

• TypeScript (ESM) for build scripts in scripts/, Jest tests in tests/. Keep Prettier and ESLint clean. Source files (JS/TS, workflow YAML, shell) start with the Apache 2.0 header in scripts/license-header.txt (npm run lint checks it; npm run format adds it).
• Any new Cowork packaging limit gets a check in tests/package-invariants.test.ts.

Git and GitHub

• Use gh for GitHub operations, and push branches to origin (no forks).
• Conventional Commit prefixes (feat:, fix:, ci:, docs:, chore:). The PR title becomes the changelog entry; label skip-changelog to opt out.
• Changes land on main via pull request. Never force-push main.

AI attribution

Mark AI-assisted commits with an Assisted-by: trailer (not Co-Authored-By:), following the Linux kernel convention adopted at Elastic:

Assisted-by: Claude Code <noreply@anthropic.com>

CI and releases

• ci.yml: lint, test, offline atk validate, and atk package on push and PR. Publishes nothing.
• generate-manifest.yml: on PRs touching skills/, commits the regenerated manifest.json.
• changelog.yml: commits a changelog entry from the PR title.
• release.yml: manual. Validates the version, bumps the manifest, stamps the changelog, and opens a release PR to main.
• release-tag.yml: when the manifest version changes on main, re-runs checks, tags v{version}, and creates a GitHub Release with elastic-copilot-cowork-{version}.zip.

Server-side validation of the release zip is a manual step; see RELEASING.md.

Security

• Never commit secrets, tokens, or M365 credentials. Never bypass git hooks with --no-verify.
• MCP connectors must use https (enforced by the package invariant tests).