Skip to content

Agent Zero AI framework

replace underscores with dashes for skills

3clyp50fee4a3c9779a
diff --git a/docs/CONTRIBUTING-SKILLS.md b/docs/CONTRIBUTING-SKILLS.md
index 079bcbc71..8f78704ab 100644
--- a/docs/CONTRIBUTING-SKILLS.md
+++ b/docs/CONTRIBUTING-SKILLS.md
@@ -460,8 +460,8 @@ Check out these well-structured skills in `usr/skills/builtin/`:
- `brainstorming/` - Requirements exploration workflow
- `debugging/` - Systematic debugging methodology
- `tdd/` - Test-driven development process
-- `code_review/` - Comprehensive review checklist
-- `create_skill/` - Meta-skill for creating new skills
+- `code-review/` - Comprehensive review checklist
+- `create-skill/` - Meta-skill for creating new skills
---
diff --git a/python/helpers/skills_cli.py b/python/helpers/skills_cli.py
index ef6f6f9ea..4cd254cae 100644
--- a/python/helpers/skills_cli.py
+++ b/python/helpers/skills_cli.py
@@ -17,7 +17,7 @@ import yaml
import re
from pathlib import Path
from typing import Optional, List, Dict, Any
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from datetime import datetime
# Add parent directory to path for imports
@@ -34,16 +34,10 @@ class Skill:
path: Path
version: str = "1.0.0"
author: str = ""
- tags: List[str] = None
- trigger_patterns: List[str] = None
+ tags: List[str] = field(default_factory=list)
+ trigger_patterns: List[str] = field(default_factory=list)
content: str = ""
- def __post_init__(self):
- if self.tags is None:
- self.tags = []
- if self.trigger_patterns is None:
- self.trigger_patterns = []
-
def get_skills_dirs() -> List[Path]:
"""Get all skill directories"""
@@ -134,8 +128,15 @@ def validate_skill(skill: Skill) -> List[str]:
issues.append("Missing required field: description")
# Name format
- if skill.name and not re.match(r"^[a-z0-9_-]+$", skill.name):
- issues.append(f"Invalid name format: '{skill.name}' (use lowercase, hyphens, underscores)")
+ if skill.name:
+ if not (1 <= len(skill.name) <= 64):
+ issues.append("Name must be 1-64 characters")
+ if not re.match(r"^[a-z0-9-]+$", skill.name):
+ issues.append(f"Invalid name format: '{skill.name}' (use lowercase letters, numbers, and hyphens)")
+ if skill.name.startswith("-") or skill.name.endswith("-"):
+ issues.append("Name must not start or end with a hyphen")
+ if "--" in skill.name:
+ issues.append("Name must not contain consecutive hyphens")
# Description length
if skill.description and len(skill.description) < 20:
diff --git a/usr/skills/builtin/api_development/SKILL.md b/usr/skills/builtin/api-development/SKILL.md
similarity index 99%
rename from usr/skills/builtin/api_development/SKILL.md
rename to usr/skills/builtin/api-development/SKILL.md
index 0893d7041..f57aee8d6 100644
--- a/usr/skills/builtin/api_development/SKILL.md
+++ b/usr/skills/builtin/api-development/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "api_development"
+name: "api-development"
description: "Best practices for designing and implementing RESTful and GraphQL APIs. Use when building, designing, or reviewing APIs."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/code_review/SKILL.md b/usr/skills/builtin/code-review/SKILL.md
similarity index 99%
rename from usr/skills/builtin/code_review/SKILL.md
rename to usr/skills/builtin/code-review/SKILL.md
index 608483d0b..be55b579b 100644
--- a/usr/skills/builtin/code_review/SKILL.md
+++ b/usr/skills/builtin/code-review/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "code_review"
+name: "code-review"
description: "Comprehensive code review skill for analyzing code quality, identifying issues, and suggesting improvements. Use when reviewing PRs or checking code quality."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/create_skill/SKILL.md b/usr/skills/builtin/create-skill/SKILL.md
similarity index 99%
rename from usr/skills/builtin/create_skill/SKILL.md
rename to usr/skills/builtin/create-skill/SKILL.md
index 4b91db991..167beba67 100644
--- a/usr/skills/builtin/create_skill/SKILL.md
+++ b/usr/skills/builtin/create-skill/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "create_skill"
+name: "create-skill"
description: "Wizard for creating new Agent Zero skills. Guides users through creating well-structured SKILL.md files. Use when users want to create custom skills."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/database_design/SKILL.md b/usr/skills/builtin/database-design/SKILL.md
similarity index 99%
rename from usr/skills/builtin/database_design/SKILL.md
rename to usr/skills/builtin/database-design/SKILL.md
index dcb3a9f6c..0b61dbae9 100644
--- a/usr/skills/builtin/database_design/SKILL.md
+++ b/usr/skills/builtin/database-design/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "database_design"
+name: "database-design"
description: "Database design, schema optimization, and query best practices. Use when designing schemas, optimizing queries, or working with databases."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/docker_devops/SKILL.md b/usr/skills/builtin/docker-devops/SKILL.md
similarity index 99%
rename from usr/skills/builtin/docker_devops/SKILL.md
rename to usr/skills/builtin/docker-devops/SKILL.md
index e6f81f3c4..d048108a4 100644
--- a/usr/skills/builtin/docker_devops/SKILL.md
+++ b/usr/skills/builtin/docker-devops/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "docker_devops"
+name: "docker-devops"
description: "Docker and DevOps best practices for containerization, orchestration, and CI/CD pipelines. Use when working with containers, deployments, or infrastructure."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/git_workflow/SKILL.md b/usr/skills/builtin/git-workflow/SKILL.md
similarity index 99%
rename from usr/skills/builtin/git_workflow/SKILL.md
rename to usr/skills/builtin/git-workflow/SKILL.md
index 9ed789d51..f95ade39c 100644
--- a/usr/skills/builtin/git_workflow/SKILL.md
+++ b/usr/skills/builtin/git-workflow/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "git_workflow"
+name: "git-workflow"
description: "Git workflow best practices for branching, committing, and collaboration. Use when working with version control."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/prompt_engineering/SKILL.md b/usr/skills/builtin/prompt-engineering/SKILL.md
similarity index 99%
rename from usr/skills/builtin/prompt_engineering/SKILL.md
rename to usr/skills/builtin/prompt-engineering/SKILL.md
index cbfd76546..c216fd9cd 100644
--- a/usr/skills/builtin/prompt_engineering/SKILL.md
+++ b/usr/skills/builtin/prompt-engineering/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "prompt_engineering"
+name: "prompt-engineering"
description: "Best practices for crafting effective prompts for LLMs. Use when designing prompts, creating system messages, or optimizing AI interactions."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/builtin/security_audit/SKILL.md b/usr/skills/builtin/security-audit/SKILL.md
similarity index 99%
rename from usr/skills/builtin/security_audit/SKILL.md
rename to usr/skills/builtin/security-audit/SKILL.md
index 13db53534..eb8738dea 100644
--- a/usr/skills/builtin/security_audit/SKILL.md
+++ b/usr/skills/builtin/security-audit/SKILL.md
@@ -1,5 +1,5 @@
---
-name: "security_audit"
+name: "security-audit"
description: "Security audit and vulnerability assessment skill. Use when reviewing code for security issues, hardening systems, or implementing security best practices."
version: "1.0.0"
author: "Agent Zero Team"
diff --git a/usr/skills/shared/SKILL/SKILL.md b/usr/skills/shared/SKILL/SKILL.md
new file mode 100644
index 000000000..664663895
--- /dev/null
+++ b/usr/skills/shared/SKILL/SKILL.md
@@ -0,0 +1,197 @@
+---
+name: docx
+description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# DOCX creation, editing, and analysis
+
+## Overview
+
+A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
+
+## Workflow Decision Tree
+
+### Reading/Analyzing Content
+Use "Text extraction" or "Raw XML access" sections below
+
+### Creating New Document
+Use "Creating a new Word document" workflow
+
+### Editing Existing Document
+- **Your own document + simple changes**
+ Use "Basic OOXML editing" workflow
+
+- **Someone else's document**
+ Use **"Redlining workflow"** (recommended default)
+
+- **Legal, academic, business, or government docs**
+ Use **"Redlining workflow"** (required)
+
+## Reading and analyzing content
+
+### Text extraction
+If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes:
+
+```bash
+# Convert document to markdown with tracked changes
+pandoc --track-changes=all path-to-file.docx -o output.md
+# Options: --track-changes=accept/reject/all
+```
+
+### Raw XML access
+You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents.
+
+#### Unpacking a file
+`python ooxml/scripts/unpack.py <office_file> <output_directory>`
+
+#### Key file structures
+* `word/document.xml` - Main document contents
+* `word/comments.xml` - Comments referenced in document.xml
+* `word/media/` - Embedded images and media files
+* Tracked changes use `<w:ins>` (insertions) and `<w:del>` (deletions) tags
+
+## Creating a new Word document
+
+When creating a new Word document from scratch, use **docx-js**, which allows you to create Word documents using JavaScript/TypeScript.
+
+### Workflow
+1. **MANDATORY - READ ENTIRE FILE**: Read [`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation.
+2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below)
+3. Export as .docx using Packer.toBuffer()
+
+## Editing an existing Word document
+
+When editing an existing Word document, use the **Document library** (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library.
+
+### Workflow
+1. **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for the Document library API and XML patterns for directly editing document files.
+2. Unpack the document: `python ooxml/scripts/unpack.py <office_file> <output_directory>`
+3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md)
+4. Pack the final document: `python ooxml/scripts/pack.py <input_directory> <office_file>`
+
+The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios.
+
+## Redlining workflow for document review
+
+This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. **CRITICAL**: For complete tracked changes, you must implement ALL changes systematically.
+
+**Batching Strategy**: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next.
+
+**Principle: Minimal, Precise Edits**
+When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the `<w:r>` element from the original and reusing it.
+
+Example - Changing "30 days" to "60 days" in a sentence:
+```python
+# BAD - Replaces entire sentence
+'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'
+
+# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
+'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'
+```
+
+### Tracked changes workflow
+
+1. **Get markdown representation**: Convert document to markdown with tracked changes preserved:
+ ```bash
+ pandoc --track-changes=all path-to-file.docx -o current.md
+ ```
+
+2. **Identify and group changes**: Review the document and identify ALL changes needed, organizing them into logical batches:
+
+ **Location methods** (for finding changes in XML):
+ - Section/heading numbers (e.g., "Section 3.2", "Article IV")
+ - Paragraph identifiers if numbered
+ - Grep patterns with unique surrounding text
+ - Document structure (e.g., "first paragraph", "signature block")
+ - **DO NOT use markdown line numbers** - they don't map to XML structure
+
+ **Batch organization** (group 3-10 related changes per batch):
+ - By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates"
+ - By type: "Batch 1: Date corrections", "Batch 2: Party name changes"
+ - By complexity: Start with simple text replacements, then tackle complex structural changes
+ - Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6"
+
+3. **Read documentation and unpack**:
+ - **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Pay special attention to the "Document Library" and "Tracked Change Patterns" sections.
+ - **Unpack the document**: `python ooxml/scripts/unpack.py <file.docx> <dir>`
+ - **Note the suggested RSID**: The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b.
+
+4. **Implement changes in batches**: Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach:
+ - Makes debugging easier (smaller batch = easier to isolate errors)
+ - Allows incremental progress
+ - Maintains efficiency (batch size of 3-10 changes works well)
+
+ **Suggested batch groupings:**
+ - By document section (e.g., "Section 3 changes", "Definitions", "Termination clause")
+ - By change type (e.g., "Date changes", "Party name updates", "Legal term replacements")
+ - By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document")
+
+ For each batch of related changes:
+
+ **a. Map text to XML**: Grep for text in `word/document.xml` to verify how text is split across `<w:r>` elements.
+
+ **b. Create and run script**: Use `get_node` to find nodes, implement changes, then `doc.save()`. See **"Document Library"** section in ooxml.md for patterns.
+
+ **Note**: Always grep `word/document.xml` immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run.
+
+5. **Pack the document**: After all batches are complete, convert the unpacked directory back to .docx:
+ ```bash
+ python ooxml/scripts/pack.py unpacked reviewed-document.docx
+ ```
+
+6. **Final verification**: Do a comprehensive check of the complete document:
+ - Convert final document to markdown:
+ ```bash
+ pandoc --track-changes=all reviewed-document.docx -o verification.md
+ ```
+ - Verify ALL changes were applied correctly:
+ ```bash
+ grep "original phrase" verification.md # Should NOT find it
+ grep "replacement phrase" verification.md # Should find it
+ ```
+ - Check that no unintended changes were introduced
+
+
+## Converting Documents to Images
+
+To visually analyze Word documents, convert them to images using a two-step process:
+
+1. **Convert DOCX to PDF**:
+ ```bash
+ soffice --headless --convert-to pdf document.docx
+ ```
+
+2. **Convert PDF pages to JPEG images**:
+ ```bash
+ pdftoppm -jpeg -r 150 document.pdf page
+ ```
+ This creates files like `page-1.jpg`, `page-2.jpg`, etc.
+
+Options:
+- `-r 150`: Sets resolution to 150 DPI (adjust for quality/size balance)
+- `-jpeg`: Output JPEG format (use `-png` for PNG if preferred)
+- `-f N`: First page to convert (e.g., `-f 2` starts from page 2)
+- `-l N`: Last page to convert (e.g., `-l 5` stops at page 5)
+- `page`: Prefix for output files
+
+Example for specific range:
+```bash
+pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page # Converts only pages 2-5
+```
+
+## Code Style Guidelines
+**IMPORTANT**: When generating code for DOCX operations:
+- Write concise code
+- Avoid verbose variable names and redundant operations
+- Avoid unnecessary print statements
+
+## Dependencies
+
+Required dependencies (install if not available):
+
+- **pandoc**: `sudo apt-get install pandoc` (for text extraction)
+- **docx**: `npm install -g docx` (for creating new documents)
+- **LibreOffice**: `sudo apt-get install libreoffice` (for PDF conversion)
+- **Poppler**: `sudo apt-get install poppler-utils` (for pdftoppm to convert PDF to images)
+- **defusedxml**: `pip install defusedxml` (for secure XML parsing)
\ No newline at end of file