Agent Zero AI framework
replace underscores with dashes for skills
3clyp50fee4a3c9779a
diff --git a/docs/CONTRIBUTING-SKILLS.md b/docs/CONTRIBUTING-SKILLS.mdindex 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.pyindex ef6f6f9ea..4cd254cae 100644--- a/python/helpers/skills_cli.py+++ b/python/helpers/skills_cli.py@@ -17,7 +17,7 @@ import yamlimport refrom pathlib import Pathfrom typing import Optional, List, Dict, Any-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom datetime import datetime# Add parent directory to path for imports@@ -34,16 +34,10 @@ class Skill:path: Pathversion: 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 lengthif skill.description and len(skill.description) < 20:diff --git a/usr/skills/builtin/api_development/SKILL.md b/usr/skills/builtin/api-development/SKILL.mdsimilarity index 99%rename from usr/skills/builtin/api_development/SKILL.mdrename to usr/skills/builtin/api-development/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/code_review/SKILL.mdrename to usr/skills/builtin/code-review/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/create_skill/SKILL.mdrename to usr/skills/builtin/create-skill/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/database_design/SKILL.mdrename to usr/skills/builtin/database-design/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/docker_devops/SKILL.mdrename to usr/skills/builtin/docker-devops/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/git_workflow/SKILL.mdrename to usr/skills/builtin/git-workflow/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/prompt_engineering/SKILL.mdrename to usr/skills/builtin/prompt-engineering/SKILL.mdindex 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.mdsimilarity index 99%rename from usr/skills/builtin/security_audit/SKILL.mdrename to usr/skills/builtin/security-audit/SKILL.mdindex 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.mdnew file mode 100644index 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