echo-agent 0.1.0__py3-none-any.whl

echo_agent/_bundled/skills/development/skill-creator/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: skill-creator
+description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend the agent's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform the agent from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else the agent needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: the agent is already very smart.** Only add context the agent doesn't already have. Challenge each piece of information: "Does the agent really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that the agent reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context.
+
+- **When to include**: For documentation that the agent should reference while working
+- **Examples**: `references/api_docs.md`, `references/policies.md`
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output the agent produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png`, `assets/slides.pptx`, `assets/frontend-template/`
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+
+The skill should only contain the information needed for an AI agent to do the job at hand.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by the agent (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+```
+
+**Pattern 2: Domain-specific organization**
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+    ├── finance.md (revenue, billing metrics)
+    ├── sales.md (opportunities, pipeline)
+    └── product.md (API usage, features)
+```
+
+**Pattern 3: Conditional details**
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+For simple edits, modify the XML directly.
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+```
+
+**Important guidelines:**
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
+- When generating names, generate a name under 64 characters (letters, digits, hyphens).
+- Prefer short, verb-led phrases that describe the action.
+- Name the skill folder exactly after the skill name.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support?"
+- "Can you give some examples of how this skill would be used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions at once. Prefer 1-2 targeted questions.
+
+### Step 2: Planning Reusable Skill Contents
+
+Before writing the skill, plan what resources it needs:
+
+- **Scripts**: For deterministic operations that need consistency
+- **References**: For detailed documentation the agent should reference
+- **Assets**: For files used in output (templates, images, etc.)
+
+### Step 3: Initializing a Skill
+
+Use the bundled initialization script:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-path>
+scripts/init_skill.py <skill-name> --path <output-path> --resources scripts,references
+scripts/init_skill.py <skill-name> --path <output-path> --resources scripts --examples
+```
+
+This creates a skill directory with a SKILL.md template and optional resource directories.
+
+### Step 4: Editing the Skill
+
+#### Frontmatter
+
+Required fields:
+
+```yaml
+---
+name: my-skill-name
+description: >-
+  Clear description of what this skill does and when to use it.
+  Include trigger scenarios, file types, or tasks that should activate this skill.
+  Example: "Process and manipulate PDF files including merging, splitting, extracting text,
+  filling forms, or any other document tasks"
+---
+```
+
+Keep frontmatter minimal. `metadata` and `always` are also supported when needed, but avoid adding extra fields unless they are actually required.
+
+#### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file. The packaging process automatically validates the skill first:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+   Security restriction: symlinks are rejected and packaging fails when any symlink is present.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again

echo_agent/_bundled/skills/development/skill-creator/scripts/init_skill.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples]
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-new-skill --path skills/public --resources scripts,references
+    init_skill.py my-api-helper --path skills/private --resources scripts --examples
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_RESOURCES = {"scripts", "references", "assets"}
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: "Complete this description with what the skill does and when to use it. Include the trigger scenarios, file types, or tasks that should activate this skill."
+---
+
+# {skill_title}
+
+## Overview
+
+[Write 1-2 sentences explaining what this skill enables.]
+
+## Structuring This Skill
+
+[Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Structure: ## Overview -> ## Workflow Decision Tree -> ## Step 1 -> ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Structure: ## Overview -> ## Quick Start -> ## Task Category 1 -> ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Structure: ## Overview -> ## Guidelines -> ## Specifications -> ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Structure: ## Overview -> ## Core Capabilities -> ### 1. Feature -> ### 2. Feature...
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [Replace with the first main section based on the chosen structure]
+
+[Add content here.]
+
+## Resources (optional)
+
+Create only the resource directories this skill actually needs. Delete this section if no resources are required.
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform the agent's process and thinking.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output the agent produces.
+
+---
+
+**Not every skill requires all three types of resources.**
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+Replace with actual implementation or delete if not needed.
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+## When to Load This Reference
+
+The agent should load this reference when:
+- [Describe specific scenarios]
+"""
+
+EXAMPLE_ASSET_README = """# Assets for {skill_title}
+
+Place files here that should be used in the agent's output (templates, images, fonts, etc.).
+These files are NOT loaded into context — they are used directly in output.
+"""
+
+
+def normalize_skill_name(raw_name: str) -> str:
+    name = raw_name.strip().lower()
+    name = re.sub(r"[^a-z0-9]+", "-", name)
+    name = name.strip("-")
+    return name
+
+
+def parse_resources(resources_str: str) -> list[str]:
+    if not resources_str.strip():
+        return []
+    resources = [r.strip().lower() for r in resources_str.split(",") if r.strip()]
+    invalid = [r for r in resources if r not in ALLOWED_RESOURCES]
+    if invalid:
+        print(f"[ERROR] Invalid resource types: {', '.join(invalid)}")
+        print(f"   Allowed: {', '.join(sorted(ALLOWED_RESOURCES))}")
+        sys.exit(1)
+    return resources
+
+
+def init_skill(skill_name: str, base_path: str, resources: list[str], examples: bool = False) -> bool:
+    skill_title = skill_name.replace("-", " ").title()
+    skill_path = Path(base_path) / skill_name
+
+    if skill_path.exists():
+        print(f"[ERROR] Directory already exists: {skill_path}")
+        return False
+
+    skill_path.mkdir(parents=True, exist_ok=True)
+
+    skill_md = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
+    (skill_path / "SKILL.md").write_text(skill_md, encoding="utf-8")
+    print(f"  Created: {skill_path / 'SKILL.md'}")
+
+    for resource in resources:
+        resource_dir = skill_path / resource
+        resource_dir.mkdir(exist_ok=True)
+        print(f"  Created: {resource_dir}/")
+
+        if examples:
+            if resource == "scripts":
+                example_file = resource_dir / f"example_{skill_name.replace('-', '_')}.py"
+                example_file.write_text(
+                    EXAMPLE_SCRIPT.format(skill_name=skill_name), encoding="utf-8"
+                )
+                print(f"  Created: {example_file}")
+            elif resource == "references":
+                example_file = resource_dir / "README.md"
+                example_file.write_text(
+                    EXAMPLE_REFERENCE.format(skill_title=skill_title), encoding="utf-8"
+                )
+                print(f"  Created: {example_file}")
+            elif resource == "assets":
+                example_file = resource_dir / "README.md"
+                example_file.write_text(
+                    EXAMPLE_ASSET_README.format(skill_title=skill_title), encoding="utf-8"
+                )
+                print(f"  Created: {example_file}")
+
+    print(f"\n[OK] Skill '{skill_name}' initialized at: {skill_path}")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Initialize a new skill directory with a SKILL.md template.",
+    )
+    parser.add_argument("skill_name", help="Skill name (normalized to hyphen-case)")
+    parser.add_argument("--path", required=True, help="Output directory for the skill")
+    parser.add_argument(
+        "--resources",
+        default="",
+        help="Comma-separated list: scripts,references,assets",
+    )
+    parser.add_argument(
+        "--examples",
+        action="store_true",
+        help="Create example files inside the selected resource directories",
+    )
+    args = parser.parse_args()
+
+    raw_skill_name = args.skill_name
+    skill_name = normalize_skill_name(raw_skill_name)
+    if not skill_name:
+        print("[ERROR] Skill name must include at least one letter or digit.")
+        sys.exit(1)
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        print(
+            f"[ERROR] Skill name '{skill_name}' is too long ({len(skill_name)} characters). "
+            f"Maximum is {MAX_SKILL_NAME_LENGTH} characters."
+        )
+        sys.exit(1)
+    if skill_name != raw_skill_name:
+        print(f"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.")
+
+    resources = parse_resources(args.resources)
+    if args.examples and not resources:
+        print("[ERROR] --examples requires --resources to be set.")
+        sys.exit(1)
+
+    path = args.path
+
+    print(f"Initializing skill: {skill_name}")
+    print(f"   Location: {path}")
+    if resources:
+        print(f"   Resources: {', '.join(resources)}")
+        if args.examples:
+            print("   Examples: enabled")
+    else:
+        print("   Resources: none (create as needed)")
+    print()
+
+    result = init_skill(skill_name, path, resources, args.examples)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

echo_agent/_bundled/skills/development/skill-creator/scripts/package_skill.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+    python package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python package_skill.py skills/public/my-skill
+    python package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+from quick_validate import validate_skill
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+        return True
+    except ValueError:
+        return False
+
+
+def _cleanup_partial_archive(skill_filename: Path) -> None:
+    try:
+        if skill_filename.exists():
+            skill_filename.unlink()
+    except OSError:
+        return None
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a .skill file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the .skill file
+
+    Returns:
+        Path to the created .skill file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    if not skill_path.exists():
+        print(f"[ERROR] Skill folder not found: {skill_path}")
+        return None
+
+    if not skill_path.is_dir():
+        print(f"[ERROR] Path is not a directory: {skill_path}")
+        return None
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        print(f"[ERROR] SKILL.md not found in {skill_path}")
+        return None
+
+    print("Validating skill...")
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        print(f"[ERROR] Validation failed: {message}")
+        print("   Please fix the validation errors before packaging.")
+        return None
+    print(f"[OK] {message}\n")
+
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    skill_filename = output_path / f"{skill_name}.skill"
+
+    EXCLUDED_DIRS = {".git", ".svn", ".hg", "__pycache__", "node_modules"}
+
+    files_to_package = []
+    resolved_archive = skill_filename.resolve()
+
+    for file_path in skill_path.rglob("*"):
+        if file_path.is_symlink():
+            print(f"[ERROR] Symlink not allowed in packaged skill: {file_path}")
+            _cleanup_partial_archive(skill_filename)
+            return None
+
+        rel_parts = file_path.relative_to(skill_path).parts
+        if any(part in EXCLUDED_DIRS for part in rel_parts):
+            continue
+
+        if file_path.is_file():
+            resolved_file = file_path.resolve()
+            if not _is_within(resolved_file, skill_path):
+                print(f"[ERROR] File escapes skill root: {file_path}")
+                _cleanup_partial_archive(skill_filename)
+                return None
+            if resolved_file == resolved_archive:
+                print(f"[WARN] Skipping output archive: {file_path}")
+                continue
+            files_to_package.append(file_path)
+
+    try:
+        with zipfile.ZipFile(skill_filename, "w", zipfile.ZIP_DEFLATED) as zipf:
+            for file_path in files_to_package:
+                arcname = Path(skill_name) / file_path.relative_to(skill_path)
+                zipf.write(file_path, arcname)
+                print(f"  Added: {arcname}")
+
+        print(f"\n[OK] Successfully packaged skill to: {skill_filename}")
+        return skill_filename
+
+    except Exception as e:
+        _cleanup_partial_archive(skill_filename)
+        print(f"[ERROR] Error creating .skill file: {e}")
+        return None
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python package_skill.py <path/to/skill-folder> [output-directory]")
+        print("\nExample:")
+        print("  python package_skill.py skills/public/my-skill")
+        print("  python package_skill.py skills/public/my-skill ./dist")
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    print(f"Packaging skill: {skill_path}")
+    if output_dir:
+        print(f"   Output directory: {output_dir}")
+    print()
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()