Skip to content

Commit 62df45f

Browse files
kriss145kriss145
authored
Merge pull request #31 from codee-sh/chore/add-skils
Add agent skills registry and docs instructions
2 parents 680f488 + dd40d44 commit 62df45f

5 files changed

Lines changed: 227 additions & 0 deletions

File tree

‎.ai/skills/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Agent Skills (Cursor + Codex)
2+
3+
This directory contains project-level skills for AI coding agents.
4+
5+
## Structure
6+
7+
```
8+
.ai/skills/
9+
plugin-docs-authoring/
10+
SKILL.md
11+
template-blocks-architecture/
12+
SKILL.md
13+
release-pr-hygiene/
14+
SKILL.md
15+
medusa-plugin-context/
16+
SKILL.md
17+
```
18+
19+
## Linking to Cursor and Codex
20+
21+
Use a single source (`.ai/skills`) and symlink it for each tool:
22+
23+
```bash
24+
mkdir -p .cursor .codex
25+
ln -sfn ../.ai/skills .cursor/skills
26+
ln -sfn ../.ai/skills .codex/skills
27+
```

‎.ai/skills/docs/SKILL.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
name: plugin-docs-authoring
3+
description: Rules for writing and updating plugin documentation. Use when creating new docs pages, updating existing docs (README, docs/*.md), or reviewing documentation changes.
4+
---
5+
6+
## Prerequisites
7+
8+
Read `AGENTS.md` first for terminology, architecture, and template types.
9+
This skill only covers documentation-specific rules.
10+
11+
## File Responsibilities
12+
13+
Each file has a strict scope. Do not mix responsibilities between files.
14+
15+
| File | Scope | Tone |
16+
|------|-------|------|
17+
| `README.md` | High-level overview, install, basic setup, links to docs | Short, navigational |
18+
| `docs/configuration.md` | Plugin options only | Technical, example-driven |
19+
| `docs/admin.md` | Admin panel user guide — what you can do, typical workflow | User-facing, no endpoints |
20+
21+
## Writing Rules
22+
23+
### Structure
24+
25+
1. Start every page with a one-sentence summary of what the page covers.
26+
2. Use `##` for main sections, `###` for subsections. Do not go deeper than `####`.
27+
3. Put "what the user can do" before technical details.
28+
4. End pages with a `## See Also` section linking to related docs.
29+
30+
### Style
31+
32+
1. Write in English.
33+
2. Use short sentences and short paragraphs.
34+
3. Prefer bullet lists over long prose.
35+
4. Use code blocks for every example — never inline large snippets.
36+
5. Do not use emojis.
37+
38+
### Cross-referencing
39+
40+
1. Do not duplicate content between files — link to the authoritative page.
41+
2. If you remove a page, update all references across docs and README.
42+
3. Keep all internal links relative (`./blocks.md`, `../blocks.md`).
43+
44+
## Checklist (run before finishing)
45+
46+
- [ ] Does the content match the current architecture?
47+
- [ ] Is `docs/admin.md` still non-technical (no raw endpoints)?
48+
- [ ] Is `README.md` still short and navigational?
49+
- [ ] Are there any dead links?
50+
- [ ] Is there duplicated content between files?
51+
52+
## Workflow
53+
54+
When asked to update or create docs:
55+
56+
1. Read this skill first.
57+
2. Identify which files are affected (use the File Responsibilities table).
58+
3. Read the current state of those files.
59+
4. Make changes following the rules above.
60+
5. Run the checklist.
61+
6. Report: list of changed files + short summary of what and why.

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@codee-sh/medusa-plugin-automations": patch
3+
---
4+
5+
Add skills and agents

‎AGENTS.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# AGENTS.md
2+
3+
Instructions for AI coding agents working on this repository.
4+
5+
## Project Overview
6+
7+
Medusa plugin for automations.
8+
Provides rule-based triggers and actions
9+
for notifications and custom workflows.
10+
11+
- Package: `@codee-sh/medusa-plugin-automations`
12+
- Medusa: `>= 2.8.8`
13+
- Node.js: `>= 20`
14+
- Package manager: `yarn` (v3, see `.yarnrc.yml`)
15+
16+
## Scripts
17+
18+
```bash
19+
yarn build # build plugin (medusa plugin:build)
20+
yarn dev # develop plugin (medusa plugin:develop)
21+
yarn prepublishOnly # build before publish (medusa plugin:build)
22+
yarn publish-local # publish locally (npx medusa plugin:publish)
23+
yarn publish-package # publish to npm (dotenv npm publish --access public)
24+
yarn format # prettier write (src)
25+
yarn format:check # prettier check (src)
26+
yarn changeset # add changeset
27+
yarn version # version bump
28+
yarn release # publish via changesets
29+
yarn release:manual # build + npm publish
30+
yarn prepare-release # prep release branch
31+
```
32+
33+
## Code Style
34+
35+
- Prettier: 60-char print width, no semicolons, double quotes, trailing commas (es5)
36+
- Config: `.prettierrc`
37+
- TypeScript: ES2021, Node16 modules, strict null checks, decorators enabled
38+
- Config: `tsconfig.json`
39+
40+
## Branch Model
41+
42+
- `main` — release-ready, every commit is tagged and deployable
43+
- `develop` — nightly builds and upcoming release work
44+
- Topic branches: `feat/<name>`, `fix/<name>`, `chore/<name>`, `docs/<name>`
45+
- PRs target `develop` by default
46+
- Hotfixes branch from `main`, merge back to `main` and `develop`
47+
48+
## Versioning and Release
49+
50+
- Uses [Changesets](https://github.com/changesets/changesets) for version management
51+
- Add changeset: `yarn changeset`
52+
- Version bump: `yarn changeset version`
53+
- Release: merge release branch to `main`, tag is created automatically
54+
- CI: GitHub Actions for PR labeling and release-on-merge
55+
56+
## Architecture
57+
58+
### High-Level Flow
59+
60+
```
61+
Event/Schedule/Manual trigger
62+
→ Subscriber/Job
63+
→ Rule evaluation
64+
→ Action handlers
65+
→ Medusa Notification Module (delivery)
66+
```
67+
68+
### Source Tree
69+
70+
```
71+
src/
72+
├── admin/ # Admin panel UI
73+
├── api/ # Admin API routes (/api/admin/mpn/...)
74+
├── emails/ # Email helpers/templates
75+
├── hooks/ # React hooks for API calls
76+
├── jobs/ # Scheduled jobs
77+
├── links/ # Module links
78+
├── modules/
79+
│ └── mpn-automation/ # Core module: models, services, migrations
80+
├── providers/ # Notification providers (e.g. slack)
81+
├── subscribers/ # Medusa event subscribers
82+
├── utils/ # Helpers
83+
└── workflows/ # Automation + domain workflows
84+
```
85+
86+
### Key Modules
87+
88+
| Module | Path | Purpose |
89+
|--------|------|---------|
90+
| `mpn-automation` | `src/modules/mpn-automation/` | Core: DB models, services, migrations |
91+
| Providers | `src/providers/` | Notification providers (e.g. Slack) |
92+
| Workflows | `src/workflows/` | Automation + domain workflows |
93+
| Subscribers | `src/subscribers/` | Event listeners for triggers |
94+
95+
## Documentation
96+
97+
- `README.md` — overview, install, basic setup
98+
- `docs/configuration.md` — plugin options, actions, rules
99+
- `docs/admin.md` — admin panel user guide
100+
- `CONTRIBUTING.md` — branch model, PR rules, release process
101+
102+
## AI Skills
103+
104+
Project skills live in `skills/`.
105+
If symlinked, use `.ai/skills/` with
106+
`.cursor/skills` and `.codex/skills`.
107+
108+
| Skill | When to use |
109+
|-------|-------------|
110+
| `docs` | Writing or updating documentation |
111+
112+
## Rules for Agents
113+
114+
1. Always run `yarn format` before committing.
115+
2. Follow the branch model: feature work from `develop`, PRs to `develop`.
116+
3. Add a changeset (`yarn changeset`) for any user-facing change.
117+
4. Use consistent terminology: `automation`, `trigger`,
118+
`rule`, `action`, `mpn-automation`, `workflow`.
119+
5. When changing docs, follow the `docs` skill.
120+
6. Do not commit `.env`, `node_modules`, `.medusa/`, or build artifacts.

‎scripts/install-ai-skills.sh‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/usr/bin/env bash
2+
3+
set -euo pipefail
4+
5+
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
6+
7+
mkdir -p "$ROOT_DIR/.cursor" "$ROOT_DIR/.codex"
8+
9+
ln -sfn ../.ai/skills "$ROOT_DIR/.cursor/skills"
10+
ln -sfn ../.ai/skills "$ROOT_DIR/.codex/skills"
11+
12+
echo "Linked:"
13+
echo " - .cursor/skills -> .ai/skills"
14+
echo " - .codex/skills -> .ai/skills"

0 commit comments

Comments
 (0)