From fee4a3c9779a092110456c94ef7160509de128ca Mon Sep 17 00:00:00 2001 From: 3clyp50 Date: Mon, 2 Feb 2026 14:39:13 +0100 Subject: [PATCH] replace underscores with dashes for skills --- docs/CONTRIBUTING-SKILLS.md | 4 +- python/helpers/skills_cli.py | 23 +- .../SKILL.md | 2 +- .../{code_review => code-review}/SKILL.md | 2 +- .../{create_skill => create-skill}/SKILL.md | 2 +- .../SKILL.md | 2 +- .../{docker_devops => docker-devops}/SKILL.md | 2 +- .../{git_workflow => git-workflow}/SKILL.md | 2 +- .../SKILL.md | 2 +- .../SKILL.md | 2 +- usr/skills/shared/SKILL/SKILL.md | 197 ++++++++++++++++++ 11 files changed, 219 insertions(+), 21 deletions(-) rename usr/skills/builtin/{api_development => api-development}/SKILL.md (99%) rename usr/skills/builtin/{code_review => code-review}/SKILL.md (99%) rename usr/skills/builtin/{create_skill => create-skill}/SKILL.md (99%) rename usr/skills/builtin/{database_design => database-design}/SKILL.md (99%) rename usr/skills/builtin/{docker_devops => docker-devops}/SKILL.md (99%) rename usr/skills/builtin/{git_workflow => git-workflow}/SKILL.md (99%) rename usr/skills/builtin/{prompt_engineering => prompt-engineering}/SKILL.md (99%) rename usr/skills/builtin/{security_audit => security-audit}/SKILL.md (99%) create mode 100644 usr/skills/shared/SKILL/SKILL.md 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 ` + +#### 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 `` (insertions) and `` (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 ` +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 ` + +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 `` element from the original and reusing it. + +Example - Changing "30 days" to "60 days" in a sentence: +```python +# BAD - Replaces entire sentence +'The term is 30 days.The term is 60 days.' + +# GOOD - Only marks what changed, preserves original for unchanged text +'The term is 3060 days.' +``` + +### 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 ` + - **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 `` 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