feat: add README documentation for monitoring agent skill (#1212)

* feat: add README documentation for monitoring agent skill

Add README.md files documenting the monitoring agent skill for the
Agent Skills release. The skill enables AI agents to create and manage
Checkly monitoring resources.

- Rename compile-ai-context to prepare-ai-context for clarity
- Add README to skills/monitoring/ for public skill consumption
- Add source README to packages/cli/src/ai-context/ for build process

* Update skills/monitoring/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* refactor: update log messages in prepare-ai-context script

Use clearer, more accurate terminology in console output.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: stefanjudis

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",

…ckages/cli/scripts/compile-ai-context.ts …ckages/cli/scripts/prepare-ai-context.tspackages/cli/scripts/compile-ai-context.ts renamed to packages/cli/scripts/prepare-ai-context.ts packages/cli/scripts/compile-ai-context.ts renamed to 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)