feat: add README documentation for monitoring agent skill

packages/cli/package.json

@@ -18,9 +18,9 @@
     "clean:gen": "rimraf ./gen",
     "clean": "npm run clean:dist && npm run clean:gen",
     "prepack": "npx oclif manifest",
-    "generate:ai-context": "cross-env CHECKLY_SKIP_AUTH=1 CHECKLY_CLI_VERSION=99.0.0 ./bin/run import plan --root gen --debug-import-plan-input-file ./src/ai-context/context.fixtures.json && ts-node ./scripts/compile-ai-context.ts",
+    "prepare:ai-context": "cross-env CHECKLY_SKIP_AUTH=1 CHECKLY_CLI_VERSION=99.0.0 ./bin/run import plan --root gen --debug-import-plan-input-file ./src/ai-context/context.fixtures.json && ts-node ./scripts/prepare-ai-context.ts",
     "prepare:dist": "tsc --build",
-    "prepare": "npm run clean && npm run prepare:dist && npm run generate:ai-context",
+    "prepare": "npm run clean && npm run prepare:dist && npm run prepare:ai-context",
     "test": "vitest",
     "test:e2e": "npm run prepare && cross-env NODE_CONFIG_DIR=./e2e/config vitest -c ./vitest.config.e2e.mts",
     "test:e2e:local": "cross-env CHECKLY_BASE_URL=http://localhost:3000  CHECKLY_ENV=local npm run test:e2e",

packages/cli/scripts/compile-ai-context.ts → packages/cli/scripts/prepare-ai-context.ts

@@ -9,6 +9,7 @@ const CONTEXT_TEMPLATE_PATH = join(
 )
 const RULES_OUTPUT_DIR = join(__dirname, '../dist/ai-context')
 const SKILL_OUTPUT_DIR = join(__dirname, '../dist/ai-context/skills/monitoring')
+const README_PATH = join(__dirname, '../src/ai-context/README.md')
 
 function stripYamlFrontmatter (content: string): string {
   const frontmatterRegex = /^---\r?\n[\s\S]*?\r?\n---\r?\n+/
@@ -20,13 +21,13 @@ async function writeOutput (content: string, dir: string, filename: string): Pro
   const outputPath = join(dir, filename)
   await writeFile(outputPath, content, 'utf8')
   // eslint-disable-next-line no-console
-  console.log(`✅ Compiled to ${outputPath}`)
+  console.log(`✅ Wrote ${outputPath}`)
 }
 
-async function compileContext () {
+async function prepareContext () {
   try {
     // eslint-disable-next-line no-console
-    console.log('📝 Compiling context template with examples...')
+    console.log('📝 Preparing AI context...')
 
     let content = await readFile(CONTEXT_TEMPLATE_PATH, 'utf8')
     const examples = await readExampleCode()
@@ -41,9 +42,12 @@ async function compileContext () {
       RULES_OUTPUT_DIR,
       'checkly.rules.md',
     )
+
+    const readme = await readFile(README_PATH, 'utf8')
+    await writeOutput(readme, SKILL_OUTPUT_DIR, 'README.md')
   } catch (error) {
     // eslint-disable-next-line no-console
-    console.error('❌ Failed to compile context:', error)
+    console.error('❌ Failed to prepare AI context:', error)
     process.exit(1)
   }
 }
@@ -82,4 +86,4 @@ async function readExampleCode (): Promise<
   return examples
 }
 
-compileContext()
+prepareContext()

packages/cli/src/ai-context/README.md

@@ -0,0 +1,44 @@
+# Checkly CLI Monitoring Agent Skill
+
+This directory contains the agent skill for creating and managing end-to-end testing, monitoring, & observability with an AI-native workflow using Checkly.
+
+## Structure
+
+```
+skills/
+└── monitoring/
+    ├── README.md             # Documentation about the skill
+    └── SKILL.md              # Main skill instructions
+```
+
+## What is an Agent Skill?
+
+Agent Skills are a standardized format for giving AI agents specialized knowledge and workflows. This skill teaches agents how to:
+
+- Create and manage API checks, Browser Checks, URL monitors, and other monitors
+- Set up Playwright-based Browser and Multistep checks and Playwright Check Suites
+- Configure Heartbeat Monitors for cron jobs and scheduled tasks
+- Define alert channels (email, Slack, phone, webhooks, etc.)
+- Build dashboards and status pages
+- Follow monitoring-as-code best practices with the Checkly CLI
+
+## Using This Skill
+
+AI agents can load this skill to gain expertise in Checkly monitoring. The skill follows the [Agent Skills specification](https://agentskills.io) with:
+
+- **SKILL.md**: Core instructions loaded when the skill is activated
+
+## Progressive Disclosure
+
+The skill is structured for efficient context usage:
+
+1. **Metadata** (~80 tokens): Name and description in frontmatter
+2. **Core Instructions** (~4.5K tokens): Main SKILL.md content with construct examples
+
+Agents load what they need for each task.
+
+## Learn More
+
+- [Checkly CLI Documentation](https://www.checklyhq.com/docs/cli/overview/)
+- [Checkly Constructs Reference](https://www.checklyhq.com/docs/constructs/overview/)
+- [Agent Skills Specification](https://agentskills.io/specification.md)

skills/monitoring/README.md

@@ -0,0 +1,44 @@
+# Checkly CLI Monitoring Agent Skill
+
+This directory contains the agent skill for creating and managing end-to-end testing, monitoring, & observability with an AI-native workflow using Checkly.
+
+## Structure
+
+```
+skills/
+└── monitoring/
+    ├── README.md             # Documentation about the skill
+    └── SKILL.md              # Main skill instructions
+```
+
+## What is an Agent Skill?
+
+Agent Skills are a standardized format for giving AI agents specialized knowledge and workflows. This skill teaches agents how to:
+
+- Create and manage API checks, Browser Checks, URL monitors, and other monitors
+- Set up Playwright-based Browser and Multistep checks and Playwright Check Suites
+- Configure Heartbeat Monitors for cron jobs and scheduled tasks
+- Define alert channels (email, Slack, phone, webhooks, etc.)
+- Build dashboards and status pages
+- Follow monitoring-as-code best practices with the Checkly CLI
+
+## Using This Skill
+
+AI agents can load this skill to gain expertise in Checkly monitoring. The skill follows the [Agent Skills specification](https://agentskills.io) with:
+
+- **SKILL.md**: Core instructions loaded when the skill is activated
+
+## Progressive Disclosure
+
+The skill is structured for efficient context usage:
+
+1. **Metadata** (~80 tokens): Name and description in frontmatter
+2. **Core Instructions** (~4.5K tokens): Main SKILL.md content with construct examples
+
+Agents load what they need for each task.
+
+## Learn More
+
+- [Checkly CLI Documentation](https://www.checklyhq.com/docs/cli/overview/)
+- [Checkly Constructs Reference](https://www.checklyhq.com/docs/constructs/overview/)
+- [Agent Skills Specification](https://agentskills.io/specification.md)