From db69a5375a2725a0924abd97353263819d9d1d42 Mon Sep 17 00:00:00 2001 From: viratatwebflow Date: Wed, 11 Mar 2026 23:36:25 +0530 Subject: [PATCH 1/2] update: restructure agent documentation and introduce CLAUDE.md - Replaced the symlink for CLAUDE.md with a new file containing comprehensive project documentation for Webflow Skills. - Updated AGENTS.md to reflect the new structure. - Renamed skills in the webflow-cli-skills to follow a consistent naming convention. --- AGENTS.md | 2 +- CLAUDE.md | 62 ++++++++++++++++++- README.md | 24 ++++++- .../skills/code-component-command/SKILL.md | 2 +- .../designer-extension-command/SKILL.md | 2 +- .../skills/devlink-command/SKILL.md | 2 +- .../webflow-cli-troubleshooter/SKILL.md | 2 +- .../skills/webflow-cloud-command/SKILL.md | 2 +- .../skills/component-audit/SKILL.md | 2 +- .../skills/component-scaffold/SKILL.md | 2 +- .../skills/convert-component/SKILL.md | 2 +- .../skills/deploy-guide/SKILL.md | 2 +- .../skills/local-dev-setup/SKILL.md | 2 +- .../local-dev-setup/references/EXAMPLES.md | 4 +- .../skills/pre-deploy-check/SKILL.md | 2 +- .../skills/troubleshoot-deploy/SKILL.md | 2 +- 16 files changed, 99 insertions(+), 17 deletions(-) mode change 120000 => 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 95fb99f..681311e 120000 --- a/AGENTS.md +++ b/AGENTS.md @@ -1 +1 @@ -agents/webflow-agent.md \ No newline at end of file +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 47dc3e3..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e5b376a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,61 @@ +## Project Overview + +Webflow Skills is a marketplace-ready collection of agent skills for Claude Code, Cursor, and compatible agents. Skills extend agents with specialized Webflow capabilities: CMS management, site auditing, safe publishing, code components, and CLI integration. **This is a pure documentation project** — no compiled code, just SKILL.md files that guide agent behavior. + +## Repository Structure + +Three plugin families live under `plugins/`: + +- **webflow-skills/** — CMS operations, site/asset/link audits, safe publish, FlowKit naming (10 skills) +- **webflow-code-component-skills/** — React code component scaffolding, conversion, validation, deployment (7 skills) +- **webflow-cli-skills/** — CLI wrappers for Cloud, DevLink, designer extensions (5 skills) + +Key config files: + +- `.mcp.json` — MCP server config (Webflow MCP at https://mcp.webflow.com/mcp) +- `.claude-plugin/marketplace.json` — Marketplace entry listing all 3 plugins +- `.cursor-plugin/plugin.json` + `marketplace.json` — Cursor plugin config +- `agents/webflow-agent.md` — Agent setup documentation + +## CI Validation + +CI runs on push/PR to main (`.github/workflows/ci.yml`): + +```bash +# What CI checks: +# 1. Required root files: README.md, LICENSE, AGENTS.md, CLAUDE.md (must be symlink) +# 2. Marketplace and plugin configs exist +# 3. Every skill dir under plugins/webflow-skills/skills/ has SKILL.md with name: and description: frontmatter +``` + +There is no build step, test suite, or linter config — validation is purely structural. + +## Skill Anatomy + +Each skill is a single `SKILL.md` file in its own directory: + +``` +plugins//skills//SKILL.md +``` + +Required YAML frontmatter: + +```yaml +--- +name: skill-name # 1-64 chars, lowercase alphanumeric + hyphens +description: ... # Up to 1024 chars, include trigger keywords +--- +``` + +Optional frontmatter: `license`, `model`, `allowed-tools` + +## Design Conventions + +- **Phased workflows**: Discovery → Analysis → Validation → Preview → Confirmation → Execution → Reporting +- **Safety-first**: All mutating operations require explicit user confirmation (type "confirm" or "publish", not just "yes") +- **Batch operations**: Large datasets split into 50-item batches with progress reporting +- **MCP-routed**: Webflow operations use MCP tools, never direct API calls + +## Adding/Editing Skills + +Follow `CONTRIBUTING.md`. PR title format: `feat(skills): Add [skill-name]`. Keep SKILL.md under 500 lines. Every skill needs Instructions, Examples, and Guidelines sections. diff --git a/README.md b/README.md index 3c150ea..d6022d7 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ These skills require the [Webflow MCP server](https://developers.webflow.com/mcp For detailed setup instructions, visit the [Webflow MCP Documentation](https://developers.webflow.com/mcp). -## Skills +## Webflow MCP Skills | Skill | Description | |-------|-------------| @@ -76,6 +76,28 @@ For detailed setup instructions, visit the [Webflow MCP Documentation](https://d | custom-code-management | Manage tracking scripts and custom code safely | | flowkit-naming | Apply Webflow's official FlowKit CSS naming conventions | +## Webflow CLI Skills + +| Skill | Description | +|-------|-------------| +| webflow-cli:cloud | Initialize, build, and deploy full-stack Webflow applications to Webflow Cloud hosting | +| webflow-cli:devlink | Export Webflow Designer components to React/Next.js code for external projects | +| webflow-cli:designer-extension | Build Designer Extensions for custom Webflow Designer functionality | +| webflow-cli:code-component | Create and deploy reusable React components for Webflow Designer | +| webflow-cli:troubleshooter | Diagnose and fix Webflow CLI issues including installation, auth, build, and bundle problems | + +## Webflow Code Component Skills + +| Skill | Description | +|-------|-------------| +| webflow-code-component:component-scaffold | Generate new Code Component boilerplate with React component and definition file | +| webflow-code-component:convert-component | Convert an existing React component into a Webflow Code Component | +| webflow-code-component:component-audit | Audit Code Components for architecture decisions and Shadow DOM compatibility | +| webflow-code-component:deploy-guide | Step-by-step guide for deploying Code Components to a workspace | +| webflow-code-component:local-dev-setup | Initialize a new Code Components project from scratch | +| webflow-code-component:pre-deploy-check | Pre-deployment validation for bundle size, dependencies, SSR compatibility | +| webflow-code-component:troubleshoot-deploy | Debug deployment failures with root cause analysis and fixes | + ## Resources - [Webflow MCP Documentation](https://developers.webflow.com/mcp) diff --git a/plugins/webflow-cli-skills/skills/code-component-command/SKILL.md b/plugins/webflow-cli-skills/skills/code-component-command/SKILL.md index 207fe17..3c5adf1 100644 --- a/plugins/webflow-cli-skills/skills/code-component-command/SKILL.md +++ b/plugins/webflow-cli-skills/skills/code-component-command/SKILL.md @@ -1,5 +1,5 @@ --- -name: code-component-command +name: webflow-cli:code-component description: Create and deploy reusable React components for Webflow Designer. Configure existing React projects with webflow.json, build and bundle code, validate output, and deploy to workspace using library share. Use when building custom components for designers. --- diff --git a/plugins/webflow-cli-skills/skills/designer-extension-command/SKILL.md b/plugins/webflow-cli-skills/skills/designer-extension-command/SKILL.md index 9fe3569..6446425 100644 --- a/plugins/webflow-cli-skills/skills/designer-extension-command/SKILL.md +++ b/plugins/webflow-cli-skills/skills/designer-extension-command/SKILL.md @@ -1,5 +1,5 @@ --- -name: designer-extension-command +name: webflow-cli:designer-extension description: Build Designer Extensions for custom Webflow Designer functionality. Lists available templates, initializes extension projects from templates (default/react/typescript-alt), bundles extensions for upload, and serves locally for development. --- diff --git a/plugins/webflow-cli-skills/skills/devlink-command/SKILL.md b/plugins/webflow-cli-skills/skills/devlink-command/SKILL.md index d94dec0..6361047 100644 --- a/plugins/webflow-cli-skills/skills/devlink-command/SKILL.md +++ b/plugins/webflow-cli-skills/skills/devlink-command/SKILL.md @@ -1,5 +1,5 @@ --- -name: devlink-command +name: webflow-cli:devlink description: Export Webflow Designer components to React/Next.js code for external projects. Configure devlink settings in webflow.json, sync design updates with devlink sync, validate generated code, show diffs, and provide integration examples. Use when building with Webflow designs in React/Next.js. --- diff --git a/plugins/webflow-cli-skills/skills/webflow-cli-troubleshooter/SKILL.md b/plugins/webflow-cli-skills/skills/webflow-cli-troubleshooter/SKILL.md index 68e1159..1639b1e 100644 --- a/plugins/webflow-cli-skills/skills/webflow-cli-troubleshooter/SKILL.md +++ b/plugins/webflow-cli-skills/skills/webflow-cli-troubleshooter/SKILL.md @@ -1,5 +1,5 @@ --- -name: webflow-cli-troubleshooter +name: webflow-cli:troubleshooter description: Diagnose and fix Webflow CLI issues including installation problems, authentication failures, build errors, and bundle problems. Uses CLI diagnostic flags (--version, --help, --verbose, --debug-bundler) for troubleshooting. --- diff --git a/plugins/webflow-cli-skills/skills/webflow-cloud-command/SKILL.md b/plugins/webflow-cli-skills/skills/webflow-cloud-command/SKILL.md index 6af681e..ee32ce1 100644 --- a/plugins/webflow-cli-skills/skills/webflow-cloud-command/SKILL.md +++ b/plugins/webflow-cli-skills/skills/webflow-cloud-command/SKILL.md @@ -1,5 +1,5 @@ --- -name: webflow-cloud-command +name: webflow-cli:cloud description: Initialize, build, and deploy full-stack Webflow applications to Webflow Cloud hosting. List available templates, initialize projects with cloud init, and deploy with comprehensive validation. Use when creating or deploying Webflow Cloud applications. --- diff --git a/plugins/webflow-code-component-skills/skills/component-audit/SKILL.md b/plugins/webflow-code-component-skills/skills/component-audit/SKILL.md index 37fef90..3004271 100644 --- a/plugins/webflow-code-component-skills/skills/component-audit/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/component-audit/SKILL.md @@ -1,5 +1,5 @@ --- -name: component-audit +name: webflow-code-component:component-audit description: Audit Webflow Code Components for architecture decisions - prop exposure, state management, slot opportunities, and Shadow DOM compatibility. Focused on Webflow-specific patterns, not generic React best practices. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: diff --git a/plugins/webflow-code-component-skills/skills/component-scaffold/SKILL.md b/plugins/webflow-code-component-skills/skills/component-scaffold/SKILL.md index 11c348d..b6d752b 100644 --- a/plugins/webflow-code-component-skills/skills/component-scaffold/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/component-scaffold/SKILL.md @@ -1,5 +1,5 @@ --- -name: component-scaffold +name: webflow-code-component:component-scaffold description: Generate new Webflow Code Component boilerplate with React component, definition file, and optional styling. Automatically checks prerequisites and can set up missing config/dependencies. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: diff --git a/plugins/webflow-code-component-skills/skills/convert-component/SKILL.md b/plugins/webflow-code-component-skills/skills/convert-component/SKILL.md index e22a54e..31fc3e2 100644 --- a/plugins/webflow-code-component-skills/skills/convert-component/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/convert-component/SKILL.md @@ -1,5 +1,5 @@ --- -name: convert-component +name: webflow-code-component:convert-component description: Convert an existing React component into a Webflow Code Component. Analyzes TypeScript props, maps to Webflow prop types, generates the .webflow.tsx definition file, and identifies required modifications. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: diff --git a/plugins/webflow-code-component-skills/skills/deploy-guide/SKILL.md b/plugins/webflow-code-component-skills/skills/deploy-guide/SKILL.md index 1e883b0..16d4aec 100644 --- a/plugins/webflow-code-component-skills/skills/deploy-guide/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/deploy-guide/SKILL.md @@ -1,5 +1,5 @@ --- -name: deploy-guide +name: webflow-code-component:deploy-guide description: Step-by-step guide for deploying Webflow Code Components to a workspace. Covers authentication, pre-flight checks, deployment execution, and verification. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: diff --git a/plugins/webflow-code-component-skills/skills/local-dev-setup/SKILL.md b/plugins/webflow-code-component-skills/skills/local-dev-setup/SKILL.md index 3fa08d5..64ac7f2 100644 --- a/plugins/webflow-code-component-skills/skills/local-dev-setup/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/local-dev-setup/SKILL.md @@ -1,5 +1,5 @@ --- -name: local-dev-setup +name: webflow-code-component:local-dev-setup description: Initialize a new Webflow Code Components project from scratch. Creates project structure, installs dependencies, configures webflow.json, and sets up development environment. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: diff --git a/plugins/webflow-code-component-skills/skills/local-dev-setup/references/EXAMPLES.md b/plugins/webflow-code-component-skills/skills/local-dev-setup/references/EXAMPLES.md index eee7fdc..5848062 100644 --- a/plugins/webflow-code-component-skills/skills/local-dev-setup/references/EXAMPLES.md +++ b/plugins/webflow-code-component-skills/skills/local-dev-setup/references/EXAMPLES.md @@ -280,8 +280,8 @@ npx webflow library share --- 💡 **Tips:** -- Use `component-scaffold` skill to quickly create new components -- Run `pre-deploy-check` skill before deploying +- Use `webflow-code-component:component-scaffold` skill to quickly create new components +- Run `webflow-code-component:pre-deploy-check` skill before deploying - Keep bundle under 50MB ``` diff --git a/plugins/webflow-code-component-skills/skills/pre-deploy-check/SKILL.md b/plugins/webflow-code-component-skills/skills/pre-deploy-check/SKILL.md index 78dd64d..bf2582f 100644 --- a/plugins/webflow-code-component-skills/skills/pre-deploy-check/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/pre-deploy-check/SKILL.md @@ -1,5 +1,5 @@ --- -name: pre-deploy-check +name: webflow-code-component:pre-deploy-check description: Pre-deployment validation for Webflow Code Components. Checks bundle size, dependencies, prop configurations, SSR compatibility, styling setup, and common issues before running webflow library share. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: diff --git a/plugins/webflow-code-component-skills/skills/troubleshoot-deploy/SKILL.md b/plugins/webflow-code-component-skills/skills/troubleshoot-deploy/SKILL.md index 6f8a724..2ef49c0 100644 --- a/plugins/webflow-code-component-skills/skills/troubleshoot-deploy/SKILL.md +++ b/plugins/webflow-code-component-skills/skills/troubleshoot-deploy/SKILL.md @@ -1,5 +1,5 @@ --- -name: troubleshoot-deploy +name: webflow-code-component:troubleshoot-deploy description: Debug deployment failures for Webflow Code Components. Analyzes error messages, identifies root causes, and provides specific fixes for common issues. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: From 6adf2a78549c5af9c9558beeb9aef1dd5b9f5664 Mon Sep 17 00:00:00 2001 From: viratatwebflow Date: Wed, 11 Mar 2026 23:40:59 +0530 Subject: [PATCH 2/2] fix: update CI workflow checks for CLAUDE.md and AGENTS.md - Changed the check for CLAUDE.md from a symlink to a regular file. - Updated the check for AGENTS.md to verify it as a symlink instead of a regular file. --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3f48980..3ba5a5e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,8 +22,8 @@ jobs: # Check root files test -f README.md || (echo "Missing README.md" && exit 1) test -f LICENSE || (echo "Missing LICENSE" && exit 1) - test -f AGENTS.md || (echo "Missing AGENTS.md" && exit 1) - test -L CLAUDE.md || (echo "Missing CLAUDE.md symlink" && exit 1) + test -f CLAUDE.md || (echo "Missing CLAUDE.md" && exit 1) + test -L AGENTS.md || (echo "Missing AGENTS.md symlink" && exit 1) # Check marketplace config test -f .claude-plugin/marketplace.json || (echo "Missing .claude-plugin/marketplace.json" && exit 1)