Skip to main content
This guide walks you through creating new skills for the Webflow Agent Skills repository, from scaffolding to publication.

​
Quick Start

The fastest way to create a new skill is using the add-skill.js script: 
node scripts/add-skill.js <skill-name> "<description>"

node scripts/add-skill.js webflow-forms "Help agents work with Webflow Forms API"
This will:
  1. Create skills/webflow-forms/ directory
  2. Generate SKILL.md with proper frontmatter
  3. Run sync-skills.js to register the skill
  4. Update manifest.json, plugin files, and README

​
Skill Structure

Each skill follows a consistent directory structure: 
skills/<skill-name>/
├── SKILL.md                    # Entry point with frontmatter + overview + reference index
├── references/                 # Detailed reference docs (API guides, guidelines, etc.)
├── scripts/                    # Helper scripts for the skill
└── assets/                     # Static assets (CSS, images, etc.)

​
The SKILL.md File

The SKILL.md file is the entry point for your skill and must include YAML frontmatter: 
---
name: skill-name
description: One-line description used for discovery and matching.
license: MIT
metadata:
  author: "224 Industries"
  version: "1.0.0"
  keywords: "ai, agent, skill, keyword1, keyword2"
  repository: "https://github.com/224-industries/webflow-skills"
---
The author and repository fields are automatically populated from manifest.json by the sync script.

​
Frontmatter Field Reference

FieldRequiredDescription
name✅Skill identifier (lowercase-with-hyphens)
description✅One-line description for discovery and matching
license✅Must be an OSI-approved license (typically MIT)
metadata.author✅Author name (auto-synced from manifest.json)
metadata.version✅Semantic version (e.g., “1.0.0”)
metadata.keywords✅Comma-separated keywords for discoverability
metadata.repository✅Repository URL (auto-synced from manifest.json)

​
SKILL.md Content Structure

After the frontmatter, your SKILL.md should include:
1

Quick start workflow

Provide a brief overview of how agents should use this skill, including common patterns and workflows.
2

Core API patterns

Include code examples demonstrating the most important API interactions for this skill.
3

Reference documentation index

Link to all files in the references/ directory with brief descriptions of each.
4

Scripts and assets

Document any helper scripts or assets included with the skill.
5

License information

Include standard MIT license footer or your chosen OSI-approved license.

​
Reference File Conventions

Every file in references/ must have YAML frontmatter with three fields: 
---
name: "Human-Readable Title"
description: "One-line summary of the file's contents."
tags: [tag1, tag2, tag3]
---

​
Field Guidelines

Descriptive title that clearly identifies the contentExamples:
  • “Elements API”
  • “Marketplace Guidelines”
  • “Designer API Authentication”
Single sentence summarizing what the file coversExamples:
  • “Complete reference for managing Webflow page elements via Designer API.”
  • “Guidelines for publishing apps to the Webflow Marketplace.”
Array of searchable keywords including:
  • API method names
  • Category terms
  • Key concepts
Example:
tags: [elements, designer-api, dom, create-element, update-element]

​
Content Style Guidelines

Plain Markdown only — Do not use JSX components like <Tabs>, <Steps>, <Note>, or <Frame>.
Reference files must use pure Markdown:
  • ✅ Use fenced code blocks with language identifiers (e.g., ```typescript)
  • ✅ Use Markdown tables for structured data
  • ✅ Use blockquotes (>) for callouts and notes
  • ✅ Include a Table of Contents with a horizontal rule separator
  • ✅ End with a Best Practices section where applicable
  • ✅ Keep references focused on one API domain or topic per file

​
Converting from Webflow Documentation

When adapting content from Webflow’s official documentation, convert JSX/HTML components to plain Markdown:
Source componentConvert to
<Tabs> / <Tab>Separate sections with ### headings
<Note> / <Warning>Blockquote (>) with bold prefix
<Steps> / <Step>Numbered list with ### sub-headings
<Accordion>Standard Markdown table or section
<Frame> / <img>Remove (image URLs won’t resolve in agent context)
<Button> / <a>Inline Markdown link [text](url)
Source (with JSX):
<Note>
Make sure to authenticate before calling the API.
</Note>

<Steps>
  <Step title="Get token">
    Call the auth endpoint
  </Step>
  <Step title="Make request">
    Include token in headers
  </Step>
</Steps>
Converted (plain Markdown):
> **Note:** Make sure to authenticate before calling the API.

### Authentication Steps

1. **Get token** — Call the auth endpoint
2. **Make request** — Include token in headers

​
Using the add-skill.js Script

The add-skill.js script automates skill creation with proper structure:

​
Script Workflow

1

Name normalization

Converts your input to lowercase-with-hyphens format:
  • "My New Skill" → "my-new-skill"
  • Removes special characters
  • Ensures valid directory name
2

Load manifest

Reads manifest.json to get:
  • Author name (defaults to “224 Industries”)
  • License (defaults to “MIT”)
  • Repository URL
3

Create skill directory

Creates skills/<skill-name>/ directory
4

Generate SKILL.md

Creates SKILL.md with properly formatted frontmatter:
---
name: skill-name
description: Your provided description
license: MIT
metadata:
  author: "224 Industries"
  version: "1.0.0"
  keywords: "ai, agent, skill"
---
5

Run sync

Automatically calls sync-skills.js to:
  • Register skill in manifest.json
  • Update plugin files
  • Update skills/index.json
  • Update README.md

​
Script Parameters

node scripts/add-skill.js <skill-name> "<description>"
ParameterRequiredDescription
skill-name✅Name of the skill (will be normalized)
description✅Brief description (use quotes if contains spaces)
Tip: Use descriptive keywords in your skill name for better discoverability. For example: webflow-forms, webflow-cms, webflow-designer.

​
After Creation

Once the script completes, you’ll see: 
Creating skill: your-skill-name

Created skills/your-skill-name/SKILL.md

Running sync-skills.js...

Found 1 agent skill(s):
  - your-skill-name

Updated manifest.json
Updated .claude-plugin/plugin.json
Updated .claude-plugin/marketplace.json
Updated .cursor-plugin/plugin.json
Updated skills/index.json
Updated README.md

Skill Sync Complete!

Skill "your-skill-name" created successfully!

Next steps:
  1. Edit skills/your-skill-name/SKILL.md to add your skill content
  2. Add keywords to the SKILL.md frontmatter for better discoverability

​
Next Steps

1

Edit SKILL.md

Add your skill’s content, including:
  • Quick start workflow
  • Core API patterns
  • Code examples
  • Reference index
2

Add reference files

Create detailed reference documentation in references/ directory:
skills/your-skill-name/references/
├── api-overview.md
├── authentication.md
└── best-practices.md
3

Update keywords

Edit the metadata.keywords field in SKILL.md frontmatter for better discoverability:
keywords: "ai, agent, skill, webflow, forms, api, designer"
4

Sync changes

Run sync script if you changed frontmatter:
node scripts/sync-skills.js
5

Test locally

Install the skill in your AI agent and test functionality before publishing.

​
Best Practices

Each skill should cover a specific domain (e.g., Forms API, CMS API, Designer API) rather than trying to be comprehensive. This makes skills easier to maintain and more useful for agents.
Add relevant keywords to improve discoverability. Include:
  • API names
  • Method names
  • Common use cases
  • Related technologies
Include full, runnable code examples that agents can use as templates. Show authentication, error handling, and common patterns.
Reference documentation should match the current Webflow API. When APIs change, update your references promptly.

Build docs developers (and LLMs) love

Get started for freeTalk to us