Add agent skills registry and docs instructions

.ai/skills/README.md

@@ -0,0 +1,27 @@
+# Agent Skills (Cursor + Codex)
+
+This directory contains project-level skills for AI coding agents.
+
+## Structure
+
+```
+.ai/skills/
+  plugin-docs-authoring/
+    SKILL.md
+  template-blocks-architecture/
+    SKILL.md
+  release-pr-hygiene/
+    SKILL.md
+  medusa-plugin-context/
+    SKILL.md
+```
+
+## Linking to Cursor and Codex
+
+Use a single source (`.ai/skills`) and symlink it for each tool:
+
+```bash
+mkdir -p .cursor .codex
+ln -sfn ../.ai/skills .cursor/skills
+ln -sfn ../.ai/skills .codex/skills
+```

.ai/skills/docs/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: plugin-docs-authoring
+description: Rules for writing and updating plugin documentation. Use when creating new docs pages, updating existing docs (README, docs/*.md), or reviewing documentation changes.
+---
+
+## Prerequisites
+
+Read `AGENTS.md` first for terminology, architecture, and template types.
+This skill only covers documentation-specific rules.
+
+## File Responsibilities
+
+Each file has a strict scope. Do not mix responsibilities between files.
+
+| File | Scope | Tone |
+|------|-------|------|
+| `README.md` | High-level overview, install, basic setup, links to docs | Short, navigational |
+| `docs/configuration.md` | Plugin options only | Technical, example-driven |
+| `docs/admin.md` | Admin panel user guide — what you can do, typical workflow | User-facing, no endpoints |
+
+## Writing Rules
+
+### Structure
+
+1. Start every page with a one-sentence summary of what the page covers.
+2. Use `##` for main sections, `###` for subsections. Do not go deeper than `####`.
+3. Put "what the user can do" before technical details.
+4. End pages with a `## See Also` section linking to related docs.
+
+### Style
+
+1. Write in English.
+2. Use short sentences and short paragraphs.
+3. Prefer bullet lists over long prose.
+4. Use code blocks for every example — never inline large snippets.
+5. Do not use emojis.
+
+### Cross-referencing
+
+1. Do not duplicate content between files — link to the authoritative page.
+2. If you remove a page, update all references across docs and README.
+3. Keep all internal links relative (`./blocks.md`, `../blocks.md`).
+
+## Checklist (run before finishing)
+
+- [ ] Does the content match the current architecture?
+- [ ] Is `docs/admin.md` still non-technical (no raw endpoints)?
+- [ ] Is `README.md` still short and navigational?
+- [ ] Are there any dead links?
+- [ ] Is there duplicated content between files?
+
+## Workflow
+
+When asked to update or create docs:
+
+1. Read this skill first.
+2. Identify which files are affected (use the File Responsibilities table).
+3. Read the current state of those files.
+4. Make changes following the rules above.
+5. Run the checklist.
+6. Report: list of changed files + short summary of what and why.

.changeset/add-skills-and-agents.md

@@ -0,0 +1,5 @@
+---
+"@codee-sh/medusa-plugin-automations": patch
+---
+
+Add skills and agents

AGENTS.md

@@ -0,0 +1,120 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on this repository.
+
+## Project Overview
+
+Medusa plugin for automations.
+Provides rule-based triggers and actions
+for notifications and custom workflows.
+
+- Package: `@codee-sh/medusa-plugin-automations`
+- Medusa: `>= 2.8.8`
+- Node.js: `>= 20`
+- Package manager: `yarn` (v3, see `.yarnrc.yml`)
+
+## Scripts
+
+```bash
+yarn build              # build plugin (medusa plugin:build)
+yarn dev                # develop plugin (medusa plugin:develop)
+yarn prepublishOnly     # build before publish (medusa plugin:build)
+yarn publish-local      # publish locally (npx medusa plugin:publish)
+yarn publish-package    # publish to npm (dotenv npm publish --access public)
+yarn format             # prettier write (src)
+yarn format:check       # prettier check (src)
+yarn changeset          # add changeset
+yarn version            # version bump
+yarn release            # publish via changesets
+yarn release:manual     # build + npm publish
+yarn prepare-release    # prep release branch
+```
+
+## Code Style
+
+- Prettier: 60-char print width, no semicolons, double quotes, trailing commas (es5)
+- Config: `.prettierrc`
+- TypeScript: ES2021, Node16 modules, strict null checks, decorators enabled
+- Config: `tsconfig.json`
+
+## Branch Model
+
+- `main` — release-ready, every commit is tagged and deployable
+- `develop` — nightly builds and upcoming release work
+- Topic branches: `feat/<name>`, `fix/<name>`, `chore/<name>`, `docs/<name>`
+- PRs target `develop` by default
+- Hotfixes branch from `main`, merge back to `main` and `develop`
+
+## Versioning and Release
+
+- Uses [Changesets](https://github.com/changesets/changesets) for version management
+- Add changeset: `yarn changeset`
+- Version bump: `yarn changeset version`
+- Release: merge release branch to `main`, tag is created automatically
+- CI: GitHub Actions for PR labeling and release-on-merge
+
+## Architecture
+
+### High-Level Flow
+
+```
+Event/Schedule/Manual trigger
+  → Subscriber/Job
+    → Rule evaluation
+      → Action handlers
+        → Medusa Notification Module (delivery)
+```
+
+### Source Tree
+
+```
+src/
+├── admin/              # Admin panel UI
+├── api/                # Admin API routes (/api/admin/mpn/...)
+├── emails/             # Email helpers/templates
+├── hooks/              # React hooks for API calls
+├── jobs/               # Scheduled jobs
+├── links/              # Module links
+├── modules/
+│   └── mpn-automation/ # Core module: models, services, migrations
+├── providers/          # Notification providers (e.g. slack)
+├── subscribers/        # Medusa event subscribers
+├── utils/              # Helpers
+└── workflows/          # Automation + domain workflows
+```
+
+### Key Modules
+
+| Module | Path | Purpose |
+|--------|------|---------|
+| `mpn-automation` | `src/modules/mpn-automation/` | Core: DB models, services, migrations |
+| Providers | `src/providers/` | Notification providers (e.g. Slack) |
+| Workflows | `src/workflows/` | Automation + domain workflows |
+| Subscribers | `src/subscribers/` | Event listeners for triggers |
+
+## Documentation
+
+- `README.md` — overview, install, basic setup
+- `docs/configuration.md` — plugin options, actions, rules
+- `docs/admin.md` — admin panel user guide
+- `CONTRIBUTING.md` — branch model, PR rules, release process
+
+## AI Skills
+
+Project skills live in `skills/`.
+If symlinked, use `.ai/skills/` with
+`.cursor/skills` and `.codex/skills`.
+
+| Skill | When to use |
+|-------|-------------|
+| `docs` | Writing or updating documentation |
+
+## Rules for Agents
+
+1. Always run `yarn format` before committing.
+2. Follow the branch model: feature work from `develop`, PRs to `develop`.
+3. Add a changeset (`yarn changeset`) for any user-facing change.
+4. Use consistent terminology: `automation`, `trigger`,
+   `rule`, `action`, `mpn-automation`, `workflow`.
+5. When changing docs, follow the `docs` skill.
+6. Do not commit `.env`, `node_modules`, `.medusa/`, or build artifacts.

scripts/install-ai-skills.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+mkdir -p "$ROOT_DIR/.cursor" "$ROOT_DIR/.codex"
+
+ln -sfn ../.ai/skills "$ROOT_DIR/.cursor/skills"
+ln -sfn ../.ai/skills "$ROOT_DIR/.codex/skills"
+
+echo "Linked:"
+echo " - .cursor/skills -> .ai/skills"
+echo " - .codex/skills  -> .ai/skills"