acf-local-json
Generate Advanced Custom Fields (ACF) Local JSON configurations for WordPress from visual designs or HTML structures. Use when creating ACF field groups, converting designs to ACF schemas, building WordPress custom fields from mockups, or when working with ACF Pro Local JSON format. Supports flexible content, repeaters, clone fields, and all ACF field types.
How do I install this agent skill?
npx skills add https://github.com/josecortezz25/local-json-acf-skill --skill acf-local-jsonIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill generates WordPress Advanced Custom Fields (ACF) JSON configurations from user-provided designs or HTML. It includes a local Python script for generating unique keys. The primary security concern is the potential for indirect prompt injection via the HTML data the skill is designed to process, which is a common risk for skills handling external content.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
5/9 files flagged
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
ACF Local JSON Builder
Generate complete ACF (Advanced Custom Fields) Local JSON configurations from images, designs, or HTML structures for WordPress development.
Core Workflow
- Analyze Input: Examine the provided image, design, or HTML structure
- Identify Components: Detect repeating patterns, content sections, and field relationships
- Map Field Types: Determine appropriate ACF field types for each component
- Generate JSON: Create the complete Local JSON configuration
- Validate Structure: Ensure proper nesting, keys, and field relationships
Field Type Detection Guidelines
From Visual Analysis
- Text inputs/headings →
text,textarea, orwysiwyg - Images →
image(considergalleryfor multiple) - Repeating cards/sections →
repeaterorflexible_content - Toggle states →
true_falseorbutton_group - Dropdowns/select boxes →
selectorradio - Date displays →
date_pickerordate_time_picker - Links/buttons →
linkorurl - Color variations →
color_picker - File downloads →
file - Numbered lists →
numberorrange - Tab interfaces →
tabfield type - Accordions →
flexible_contentwith layouts
From HTML Structure
<!-- Text Field -->
<h1>, <h2>, <p> → text/textarea/wysiwyg
<!-- Image Field -->
<img> → image field
<picture>, <source> → image with return format 'array'
<!-- Repeater Pattern -->
<div class="card"> (múltiples) → repeater
<ul><li> (dinámicos) → repeater
<!-- Flexible Content Pattern -->
Secciones variadas (hero, features, cta) → flexible_content
<!-- Link Field -->
<a href=""> → link field
<!-- True/False -->
<input type="checkbox"> → true_false
JSON Structure Template
Every ACF Local JSON file follows this structure:
{
"key": "group_unique_identifier",
"title": "Field Group Name",
"fields": [...],
"location": [...],
"menu_order": 0,
"position": "normal",
"style": "default",
"label_placement": "top",
"instruction_placement": "label",
"hide_on_screen": "",
"active": true,
"description": ""
}
Field Structure Patterns
Basic Field
{
"key": "field_unique_key",
"label": "Field Label",
"name": "field_name",
"type": "text",
"instructions": "",
"required": 0,
"conditional_logic": 0,
"wrapper": {
"width": "",
"class": "",
"id": ""
},
"default_value": "",
"placeholder": "",
"prepend": "",
"append": "",
"maxlength": ""
}
Repeater Field
{
"key": "field_repeater_key",
"label": "Items",
"name": "items",
"type": "repeater",
"instructions": "",
"required": 0,
"layout": "block",
"button_label": "Add Item",
"min": 0,
"max": 0,
"sub_fields": [
{
"key": "field_subfield_key",
"label": "Title",
"name": "title",
"type": "text",
"parent": "field_repeater_key"
}
]
}
Flexible Content
{
"key": "field_flexible_key",
"label": "Page Builder",
"name": "page_builder",
"type": "flexible_content",
"instructions": "",
"button_label": "Add Section",
"min": "",
"max": "",
"layouts": {
"layout_hero": {
"key": "layout_hero_key",
"name": "hero",
"label": "Hero Section",
"display": "block",
"sub_fields": [...]
},
"layout_features": {
"key": "layout_features_key",
"name": "features",
"label": "Features Section",
"display": "block",
"sub_fields": [...]
}
}
}
Image Field
{
"key": "field_image_key",
"label": "Image",
"name": "image",
"type": "image",
"return_format": "array",
"preview_size": "medium",
"library": "all",
"min_width": "",
"min_height": "",
"min_size": "",
"max_width": "",
"max_height": "",
"max_size": "",
"mime_types": ""
}
Key Generation Rules
-
Group Keys:
group_+ descriptive_snake_case + random_hash- Example:
group_homepage_hero_5f8a2b
- Example:
-
Field Keys:
field_+ descriptive_snake_case + random_hash- Example:
field_hero_title_9c3d1e
- Example:
-
Layout Keys:
layout_+ layout_name + random_hash- Example:
layout_hero_section_4b7e9a
- Example:
-
Uniqueness: Every key must be globally unique across all ACF installations
Location Rules
Common location patterns:
"location": [
[
{
"param": "post_type",
"operator": "==",
"value": "page"
}
]
]
"location": [
[
{
"param": "page_template",
"operator": "==",
"value": "template-homepage.php"
}
]
]
"location": [
[
{
"param": "post_type",
"operator": "==",
"value": "post"
},
{
"param": "post_category",
"operator": "==",
"value": "category:news"
}
]
]
Best Practices
- Semantic Naming: Use clear, descriptive names that reflect content purpose
- Proper Nesting: Maintain correct parent-child relationships in repeaters/flex
- Return Formats: Choose appropriate return formats (ID, array, url for images)
- Instructions: Add helpful instructions for content editors
- Defaults: Set sensible default values where appropriate
- Validation: Include min/max constraints where relevant
- Layout Types: Use
block,table, orrowlayouts appropriately - Clone Fields: Reference the clone fields documentation for reusable field sets
Output Format
Generate the complete JSON file ready to save as:
acf-json/group_[name].json
The file should be valid JSON and immediately usable in WordPress ACF Pro's Local JSON feature.
Advanced Features
For complex patterns like:
- Clone fields: See
references/clone-fields.md - Bidirectional relationships: See
references/relationships.md - Custom field types: See
references/custom-types.md - Conditional logic: See
references/conditional-logic.md
Example Workflow
User provides: Screenshot of a hero section with title, subtitle, CTA button, and background image
Analysis:
- Hero section = Field Group
- Title = text field
- Subtitle = textarea field
- CTA = link field (text + URL)
- Background = image field
Output: Complete JSON with all fields properly structured and nested
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/josecortezz25/local-json-acf-skill/acf-local-json">View acf-local-json on skillZs</a>