From 8d1fe5c49f55c286d72fb8e0050d02b40f2fc4d2 Mon Sep 17 00:00:00 2001 From: stefan judis Date: Fri, 26 Jun 2026 11:19:25 +0200 Subject: [PATCH 1/2] docs: reshuffle AI section and remove Agent Rules - Group AI nav as Rocky AI + Agent Resources (Overview, MCP Server, Skills, Markdown Access, llms.txt) - Remove the Agent Rules page and all internal links; redirect /ai/rules to /ai/overview - Clarify Skills (CLI-first, repo access) vs MCP (desktop/sandboxed) on the overview - De-duplicate Markdown Access and llms.txt content from the overview, link to the standalone pages - Move the MCP/Skills/CLI comparison table to the overview; shorten and link from the MCP server page --- ai/rules.mdx | 130 --------------------------------------------------- 1 file changed, 130 deletions(-) delete mode 100644 ai/rules.mdx diff --git a/ai/rules.mdx b/ai/rules.mdx deleted file mode 100644 index ce46a3e0..00000000 --- a/ai/rules.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: 'Checkly Rules' -description: 'Add Checkly rules files to your AI agent to provide monitoring context for your coding workflow.' -sidebarTitle: 'Agent Rules' -hidden: true ---- - -import AgentExamples from "/snippets/agent-example.mdx" -import { YoutubeEmbed } from "/snippets/youtube-embed.jsx" - - -Use the Checkly Skills instead if your coding agents supports [Agent Skills](https://agentskills.io). - - -The [`checkly.rules.md` file](https://www.checklyhq.com/docs/ai/checkly.rules.md) includes best practices, example code and required CLI commands to give your AI workflow enough context to perform Checkly-related tasks. - -Once the Checkly rules are included in your AI context window, your agent can effectively assist you in managing your monitoring setup. - -It will be able to: - - - -With enough application context, you can even create checks for your specific use cases. - - -"Can you create new API Checks for the application API endpoints?" - - -Find a live session explaining how to automate Checkly monitoring with AI below and [read the "Agentic Workflows" guide](/guides/agentic-workflows) for more details. - - - -## Claude Code - -Claude Code reads instructions from `CLAUDE.md` files. You can place these files globally (in your home directory) or locally (in your project root). Claude Code automatically includes these files in its context. - -To use Checkly rules with Claude Code, download the rules file and reference it in your `CLAUDE.md`: - - - - -```bash -mkdir -p .claude && -curl -o .claude/checkly.rules.md https://www.checklyhq.com/docs/ai/checkly.rules.md -L -echo "- examine checkly.rules.md for code generation rules" >> .claude/CLAUDE.md -``` - - - - -```powershell -New-Item -ItemType Directory -Path ".claude" -Force -Invoke-WebRequest -Uri "https://www.checklyhq.com/docs/ai/checkly.rules.md" -OutFile ".claude\checkly.rules.md" -Add-Content -Path ".claude\CLAUDE.md" -Value "- examine checkly.rules.md for code generation rules" -``` - - - - -Restart your Claude Code session to load the instructions. - -## GitHub Copilot - -GitHub Copilot reads project-level instructions from `.github/copilot-instructions.md`. This file is automatically included in Copilot's context for all chat interactions. - - - - -```bash -mkdir -p .github && curl -o .github/copilot-instructions.md "https://www.checklyhq.com/docs/ai/checkly.rules.md" -L -``` - - - - -```powershell -New-Item -ItemType Directory -Path ".github" -Force -Invoke-WebRequest -Uri "https://www.checklyhq.com/docs/ai/checkly.rules.md" -OutFile ".github\copilot-instructions.md" -``` - - - - -## Cursor - -Cursor uses `.mdc` (Markdown Cursor) files stored in `.cursor/rules/` for project-specific instructions. These rules are automatically included in Cursor's context. - - - - -```bash -mkdir -p .cursor/rules && curl -o .cursor/rules/checkly.mdc "https://www.checklyhq.com/docs/ai/checkly.rules.md" -L -``` - - - - -```powershell -New-Item -ItemType Directory -Path ".cursor\rules" -Force -Invoke-WebRequest -Uri "https://www.checklyhq.com/docs/ai/checkly.rules.md" -OutFile ".cursor\rules\checkly.mdc" -``` - - - - -You can reference the rules file explicitly using `@checkly.mdc` in your Cursor chats. - -## Windsurf - -Windsurf stores rules in `.windsurf/rules/` as Markdown files. These are included in the AI context when you interact with Windsurf's assistant. - - - - -```bash -mkdir -p .windsurf/rules && curl -o .windsurf/rules/checkly.md "https://www.checklyhq.com/docs/ai/checkly.rules.md" -L -``` - - - - -```powershell -New-Item -ItemType Directory -Path ".windsurf\rules" -Force -Invoke-WebRequest -Uri "https://www.checklyhq.com/docs/ai/checkly.rules.md" -OutFile ".windsurf\rules\checkly.md" -``` - - - - -You can reference the rules file using `@checkly.md` in your Windsurf chats. From 239e37a04331fdf4f8b85482f47ac48ab0af3f5f Mon Sep 17 00:00:00 2001 From: stefan judis Date: Fri, 26 Jun 2026 11:27:03 +0200 Subject: [PATCH 2/2] docs: apply AI section content changes Adds the file changes that were dropped from the initial commit: - AI nav regroup (Rocky AI + Agent Resources) in docs.json + /ai/rules redirect - Skills vs MCP clarification and de-duplicated Markdown/llms.txt on the overview - MCP/Skills/CLI comparison table moved to the overview; shortened on the MCP page - Sidebar renames (Overview, Skills); Rules links removed from cli/overview --- ai/llms-txt.mdx | 1 - ai/markdown-access.mdx | 1 - ai/mcp-server.mdx | 15 +---- ai/overview.mdx | 141 ++++++++--------------------------------- ai/skills.mdx | 2 +- cli/overview.mdx | 4 +- docs.json | 30 ++++++--- 7 files changed, 54 insertions(+), 140 deletions(-) diff --git a/ai/llms-txt.mdx b/ai/llms-txt.mdx index 2139440a..ec44bf2c 100644 --- a/ai/llms-txt.mdx +++ b/ai/llms-txt.mdx @@ -38,4 +38,3 @@ curl https://checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/overv - [Markdown Access](/ai/markdown-access) - [Checkly Skills](/ai/skills) -- [Checkly Rules](/ai/rules) diff --git a/ai/markdown-access.mdx b/ai/markdown-access.mdx index 828f5399..dfeb582f 100644 --- a/ai/markdown-access.mdx +++ b/ai/markdown-access.mdx @@ -61,4 +61,3 @@ Based on this, how do I set up a browser check with a custom user agent? ## Additional resources - [Checkly Skills](/ai/skills) -- [Checkly Rules](/ai/rules) diff --git a/ai/mcp-server.mdx b/ai/mcp-server.mdx index 0eec86f2..bcb39860 100644 --- a/ai/mcp-server.mdx +++ b/ai/mcp-server.mdx @@ -85,18 +85,9 @@ Create a major status page incident for the API outage, but do not notify subscr ## MCP, Skills, and CLI -MCP, Checkly Skills, and the Checkly CLI are complementary. The CLI can also read live Checkly data and remains the most capable path for scripted workflows and local Monitoring as Code projects. - -Use the MCP Server when you want a quick, OAuth-based connection from a supported client without setting up the Checkly CLI in that environment. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project. - -| Use case | Recommended path | -| --- | --- | -| Ask quick, ad hoc questions from a supported client | MCP Server | -| Inspect live Checkly data without local CLI setup | MCP Server | -| Trigger existing deployed checks from chat | MCP Server or [Checkly CLI](/cli/overview) | -| Create or edit check code | [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview) | -| Test, deploy, or automate local Monitoring as Code projects | [Checkly CLI](/cli/overview) | -| Add reusable Checkly best practices to an agent | [Checkly Skills](/ai/skills) | +MCP, Checkly Skills, and the Checkly CLI are complementary. Use the MCP Server for a quick, OAuth-based connection from a supported client. Use Checkly Skills with the CLI when your agent needs to create, edit, test, or deploy code from your local project. + +See [Skills, MCP, and the CLI](/ai/overview#skills-mcp-and-the-cli) for a full comparison of when to use each. ## Learn more diff --git a/ai/overview.mdx b/ai/overview.mdx index f98c26b5..69de8f9b 100644 --- a/ai/overview.mdx +++ b/ai/overview.mdx @@ -1,8 +1,8 @@ --- title: 'AI Agents & Coding Assistants' -description: 'Use AI agents and coding assistants with Checkly Skills, rules, and the Checkly MCP Server.' -sidebarTitle: 'Agents & Checkly' -keywords: ['mcp', 'ai', 'rules', 'generate checks', 'agents', 'context'] +description: 'Use AI agents and coding assistants with Checkly Skills and the Checkly MCP Server.' +sidebarTitle: 'Overview' +keywords: ['mcp', 'ai', 'generate checks', 'agents', 'context'] --- import AgentExamples from "/snippets/agent-example.mdx" @@ -44,128 +44,43 @@ Provide the necessary Checkly context and let your AI agent of choice do the res ## Add Checkly context to your AI agent conversation -Install [Checkly Skills](/ai/skills), add [Checkly Rules](/ai/rules), or connect the [Checkly MCP Server](/ai/mcp-server) to give your AI agent enough context to perform Checkly-related tasks. +Install [Checkly Skills](/ai/skills) or connect the [Checkly MCP Server](/ai/mcp-server) to give your AI agent enough context to perform Checkly-related tasks. - + -Let your agents pull in all required Checkly context on demand. +For coding agents with repo and code access. Author Monitoring as Code with the Checkly CLI. -Give your agents live access to Checkly account data and remote actions. - - - -Include the entire Checkly context in commands or documentation. +For desktop or sandboxed agents. Live access to Checkly account data and remote actions. -### Skills, MCP, and Rules - -**Use Skills** when your AI agent supports the [Agent Skills](https://agentskills.io) standard. Skills load context on demand, keeping your agent's context window lean until Checkly-related tasks arise. This is the recommended approach for compatible agents. - -**Use the MCP Server** when your agent needs live Checkly data or remote account actions, such as reading check status, inspecting test sessions, triggering existing checks, reading RCA, or managing status page incidents. - -**Use Rules** when your agent doesn't support skills or when you want the Checkly context always available. Rules files are loaded at session start and provide consistent context throughout your conversation. - - -## When to use the Checkly MCP Server - -The MCP concept is often used to enable LLMs to interact with external systems. It acts as a bridge between the AI model and the target system, translating natural language commands into actionable API calls or code snippets. - -The [Checkly MCP Server](/ai/mcp-server) connects MCP-compatible clients to Checkly over Streamable HTTP. It exposes tools for account context, check status and results, test sessions, result assets, root cause analyses, environment variables, status pages, incidents, and triggering existing checks. - -**Use the MCP Server for live Checkly account operations. Use Skills and the Checkly CLI for Monitoring as Code authoring.** - - -The MCP server runs remotely and cannot access your local filesystem. When you need to create, edit, test, or deploy check code, use [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview). - - -## Markdown access - -Every page in the Checkly documentation is available as markdown. This makes it easy to feed specific documentation pages into AI assistants like Claude, ChatGPT, Cursor, or any other AI tool. - - -Use [Checkly Skills](/ai/skills) to automatically provide your agent with up-to-date, agent-optimized documentation. - - -### .md endpoints - -Append `.md` to any documentation URL to get the markdown version of that page. - -**Example:** - -- **HTML:** `https://www.checklyhq.com/docs/what-is-checkly/` -- **Markdown:** `https://www.checklyhq.com/docs/what-is-checkly.md` - -The markdown version includes the full page content in plain markdown, code blocks, links preserved as markdown links, and tables formatted as markdown tables. - -```bash -# Fetch documentation content with curl -curl https://www.checklyhq.com/docs/what-is-checkly.md - -# Pipe directly to your clipboard -curl https://www.checklyhq.com/docs/what-is-checkly.md | pbcopy -``` - -### Content negotiation - -You can also request markdown by setting the `Accept` header to `text/markdown`: - -```bash -curl -H "Accept: text/markdown" https://www.checklyhq.com/docs/what-is-checkly/ -``` - -This is useful when integrating with tools or scripts that set request headers programmatically. +### Skills, MCP, and the CLI - -Modern coding agents set [these headers automatically when querying documentation](https://www.checklyhq.com/blog/state-of-ai-agent-content-negotation/). - +**Use Skills for a CLI-first workflow.** Skills are built for coding agents that have access to your repository and can run commands. The agent edits your Checkly constructs and tests, then uses the [Checkly CLI](/cli/overview) to test and deploy them. Skills load context on demand, keeping your agent's context window lean until Checkly-related tasks arise. This is the recommended approach for agents that support the [Agent Skills](https://agentskills.io) standard. -### Copy as Markdown button - -Every documentation page includes a **Copy as Markdown** button at the top of the page. Click it to copy the full page content as markdown to your clipboard. - -This is the fastest way to grab documentation for a specific topic and paste it into your AI assistant's context. - -```text -Here is the Checkly Browser Checks documentation: - -[paste markdown content] - -Based on this, how do I set up a browser check with a custom user agent? -``` +**Use the MCP Server in desktop or sandboxed environments.** Some agents, like Claude Desktop, ChatGPT, or a sandboxed assistant, can't access your repository or filesystem. The [Checkly MCP Server](/ai/mcp-server) connects these clients to Checkly over Streamable HTTP and gives them live data and remote account actions, such as reading check status, inspecting test sessions, triggering existing checks, reading RCA, or managing status page incidents. +| Use case | Recommended path | +| --- | --- | +| Ask quick, ad hoc questions from a supported client | [MCP Server](/ai/mcp-server) | +| Inspect live Checkly data without local CLI setup | [MCP Server](/ai/mcp-server) | +| Trigger existing deployed checks from chat | [MCP Server](/ai/mcp-server) or [Checkly CLI](/cli/overview) | +| Create or edit check code | [Checkly Skills](/ai/skills) with the [Checkly CLI](/cli/overview) | +| Test, deploy, or automate local Monitoring as Code projects | [Checkly CLI](/cli/overview) | +| Add reusable Checkly best practices to an agent | [Checkly Skills](/ai/skills) | -## LLMs.txt +## Feed documentation to your agent +Every Checkly documentation page is available as markdown, and an `llms.txt` index lists them all. Both make it easy to pull the exact docs your agent needs into its context. -The [llms.txt standard](https://llmstxt.org/) provides a machine-readable index of all available documentation pages. Checkly publishes an `llms.txt` file at [`checklyhq.com/llms.txt`](https://www.checklyhq.com/llms.txt) that lists every documentation page with its markdown URL and a short description. - -```txt llms.txt (first 15 lines) -# Checkly Docs - -## Docs - -- [Changing your email or password in Checkly](https://checklyhq.com/docs/admin/changing-your-email-password.md): Learn how to change your email address or password in your Checkly account -- [Creating an API key in Checkly](https://checklyhq.com/docs/admin/creating-api-key.md): Learn how to create and manage user and service API keys for the Checkly API and CLI -- [Adding team members to your Checkly account](https://checklyhq.com/docs/admin/team-management/adding-team-members.md): Learn how to invite team members to join your Checkly account and manage team collaboration -- [Using Microsoft Entra ID for Single Sign-on in Checkly](https://checklyhq.com/docs/admin/team-management/microsoft-azure-ad.md): This page illustrates the standard procedure to follow in order to get started with Microsoft Entra ID SSO (formerly Azure AD) on Checkly. -- [Multi-Factor Authentication in Checkly](https://checklyhq.com/docs/admin/team-management/multi-factor-authentication.md): Learn how to set up and manage multi-factor authentication for enhanced account security -- [Using Okta for Single Sign-on in Checkly](https://checklyhq.com/docs/admin/team-management/okta.md): This page illustrates the standard procedure to follow in order to get started with Okta SSO on Checkly. -- [Role Based Access Control in Checkly](https://checklyhq.com/docs/admin/team-management/rbac.md): Checkly roles and permissions for team members -- [Removing team members from your Checkly account](https://checklyhq.com/docs/admin/team-management/removing-team-members.md): Learn how to remove team members from your Checkly account and understand how it affects your billing -- [Using SAML for Single Sign-On in Checkly](https://checklyhq.com/docs/admin/team-management/saml-sso.md): Learn how to set up SAML-based SSO for your Checkly account with supported identity providers -- [Using SCIM provisioning in Checkly](https://checklyhq.com/docs/admin/team-management/scim-provisioning.md): Learn how to set up SCIM provisioning for Checkly using your identity provider -- [Team management in Checkly](https://checklyhq.com/docs/admin/team-management.md): Manage your team and collaborate effectively in Checkly -``` - -Use the `llms.txt` file to crawl and index the entire Checkly documentation. Every link in the file points to [the `.md` version of the page](/ai/markdown-access#md-endpoints), so you can fetch each URL directly to get the markdown content. - -```bash -# Fetch the llms.txt index -curl https://www.checklyhq.com/llms.txt + + +Append `.md` to any docs URL, request markdown with content negotiation, or copy a page as markdown. + -# Fetch a specific page from the index -curl https://checklyhq.com/docs/detect/synthetic-monitoring/browser-checks/overview.md -``` + +A machine-readable index of every documentation page for crawling and indexing. + + diff --git a/ai/skills.mdx b/ai/skills.mdx index 795d374f..33d63acc 100644 --- a/ai/skills.mdx +++ b/ai/skills.mdx @@ -1,7 +1,7 @@ --- title: 'Checkly Skills' description: 'Official Checkly skills to give any AI agent on-demand best practices, context, and product capabilities.' -sidebarTitle: 'Agent Skills' +sidebarTitle: 'Skills' --- import AgentExamples from "/snippets/agent-example.mdx" diff --git a/cli/overview.mdx b/cli/overview.mdx index 770ef86d..4c90eddc 100644 --- a/cli/overview.mdx +++ b/cli/overview.mdx @@ -67,8 +67,8 @@ Checks, Browser Checks and all other constructs. Install Checkly Skills and let AI agents generate Checkly monitoring code for you. - - Include the Checkly Rules in your conversations to generate Checkly monitoring code for you. + + Connect desktop or sandboxed agents to live Checkly account data and actions. diff --git a/docs.json b/docs.json index b76090ba..12651d18 100644 --- a/docs.json +++ b/docs.json @@ -349,19 +349,25 @@ "group": "AI", "pages": [ "ai/rocky-ai", - "ai/overview", { - "group": "MCP Server", + "group": "Agent Resources", "pages": [ - "ai/mcp-server", - "ai/mcp-server/setup", - "ai/mcp-server/tools", - "ai/mcp-server/security-and-permissions", - "ai/mcp-server/troubleshooting" + "ai/overview", + { + "group": "MCP Server", + "pages": [ + "ai/mcp-server", + "ai/mcp-server/setup", + "ai/mcp-server/tools", + "ai/mcp-server/security-and-permissions", + "ai/mcp-server/troubleshooting" + ] + }, + "ai/skills", + "ai/markdown-access", + "ai/llms-txt" ] - }, - "ai/skills", - "ai/rules" + } ] }, { @@ -1321,6 +1327,10 @@ } }, "redirects": [ + { + "source": "/ai/rules", + "destination": "/ai/overview" + }, { "source": "/detect/synthetic-monitoring/api-checks/set-up-and-tear-down", "destination": "/detect/synthetic-monitoring/api-checks/setup-and-teardown"