@openhands/extensions 0.0.1-alpha → 0.2.0

package/skills/add-skill/scripts/fetch_skill.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""
+Fetch a skill from a GitHub repository and install it locally.
+
+This script downloads OpenHands skills from GitHub repositories and installs them
+into the workspace's .agents/skills/ directory. It uses git sparse checkout to
+efficiently download only the skill directory without cloning the entire repository.
+
+Usage:
+    python fetch_skill.py <github-url> <workspace-path> [--force]
+
+Examples:
+    # Full GitHub URL with branch
+    python fetch_skill.py "https://github.com/OpenHands/extensions/tree/main/skills/docker" /workspace
+    
+    # Simplified URL (assumes 'main' branch)
+    python fetch_skill.py "https://github.com/OpenHands/extensions/skills/npm" /workspace
+    
+    # Shorthand format
+    python fetch_skill.py "OpenHands/extensions/skills/codereview" /workspace
+
+The script will:
+1. Parse the GitHub URL to extract owner, repo, branch, and skill path
+2. Use git sparse checkout to download only the specified skill directory
+3. Validate the skill has a SKILL.md file
+4. Copy the skill to <workspace>/.agents/skills/<skill-name>/
+"""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def parse_github_url(url: str) -> tuple[str, str, str, str]:
+    """
+    Parse a GitHub URL into its component parts.
+    
+    Handles multiple URL formats:
+    - Full URL: https://github.com/owner/repo/tree/branch/path/to/skill
+    - Simple URL: https://github.com/owner/repo/path/to/skill
+    - With github.com: github.com/owner/repo/skill-name
+    - Shorthand: owner/repo/skill-name
+    
+    Args:
+        url: GitHub URL in any of the supported formats
+        
+    Returns:
+        Tuple of (owner, repo, branch, skill_path)
+        - owner: GitHub username or organization
+        - repo: Repository name
+        - branch: Git branch (defaults to 'main' if not specified)
+        - skill_path: Path to the skill directory within the repo
+        
+    Raises:
+        ValueError: If the URL cannot be parsed
+    """
+    # Step 1: Normalize the URL by removing protocol prefix (https://, http://)
+    url = re.sub(r'^https?://', '', url)
+    url = url.rstrip('/')
+    
+    # Step 2: Remove github.com prefix if present
+    url = re.sub(r'^github\.com/', '', url)
+    
+    # Step 3: Try to match full URL pattern with explicit branch
+    # Pattern: owner/repo/tree/branch/path/to/skill
+    # Example: "OpenHands/extensions/tree/main/skills/docker"
+    tree_match = re.match(r'^([^/]+)/([^/]+)/tree/([^/]+)/(.+)$', url)
+    if tree_match:
+        return tree_match.group(1), tree_match.group(2), tree_match.group(3), tree_match.group(4)
+    
+    # Step 4: Fall back to simple pattern (assumes 'main' branch)
+    # Pattern: owner/repo/path/to/skill
+    # Example: "OpenHands/extensions/skills/docker"
+    parts = url.split('/')
+    if len(parts) >= 3:
+        owner = parts[0]
+        repo = parts[1]
+        skill_path = '/'.join(parts[2:])
+        return owner, repo, 'main', skill_path
+    
+    raise ValueError(f"Unable to parse GitHub URL: {url}")
+
+
+def fetch_skill(github_url: str, workspace_path: str, force: bool = False) -> str:
+    """
+    Fetch a skill from GitHub and install it to the workspace.
+    
+    This function performs the following steps:
+    1. Parses the GitHub URL to extract repository information
+    2. Creates a temporary directory for the git operation
+    3. Uses git sparse checkout to download only the skill directory (efficient!)
+    4. Validates the downloaded content is a valid skill (has SKILL.md)
+    5. Copies the skill to the workspace's .agents/skills/ directory
+    
+    Args:
+        github_url: URL to the skill on GitHub (various formats supported)
+        workspace_path: Path to the workspace root directory
+        force: If True, overwrite existing skill with same name
+        
+    Returns:
+        Path to the installed skill directory
+        
+    Raises:
+        SystemExit: If skill already exists (without --force), path not found,
+                    or skill is invalid (no SKILL.md)
+    """
+    # Parse the URL to get repository details
+    owner, repo, branch, skill_path = parse_github_url(github_url)
+    
+    # Extract skill name from the path (last component)
+    # e.g., "skills/docker" -> "docker"
+    skill_name = skill_path.rstrip('/').split('/')[-1]
+    
+    # Determine the destination directory
+    # Skills are installed to: <workspace>/.agents/skills/<skill-name>/
+    dest_dir = Path(workspace_path) / '.agents' / 'skills' / skill_name
+    
+    # Check if skill already exists - prevent accidental overwrites
+    if dest_dir.exists():
+        if not force:
+            print(f"⚠️  Skill '{skill_name}' already exists at {dest_dir}")
+            print("   Use --force to overwrite")
+            sys.exit(1)
+        print(f"Removing existing skill at {dest_dir}")
+        shutil.rmtree(dest_dir)
+    
+    # Ensure the parent directory exists (.agents/skills/)
+    dest_dir.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Use a temporary directory for the git clone operation
+    # This keeps the workspace clean and handles cleanup automatically
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Build the repository URL
+        repo_url = f"https://github.com/{owner}/{repo}.git"
+        
+        # If GITHUB_TOKEN is available, use it for authentication
+        # This enables access to private repositories
+        github_token = os.environ.get('GITHUB_TOKEN')
+        if github_token:
+            repo_url = f"https://{github_token}@github.com/{owner}/{repo}.git"
+        
+        print(f"Fetching skill '{skill_name}' from {owner}/{repo}...")
+        
+        # ============================================================
+        # Git Sparse Checkout Process
+        # ============================================================
+        # Sparse checkout allows us to download only specific directories
+        # from a repository, rather than the entire repo. This is much
+        # faster and uses less bandwidth/disk space.
+        #
+        # The process:
+        # 1. Clone with --filter=blob:none (don't download file contents yet)
+        # 2. Clone with --no-checkout (don't populate working directory)
+        # 3. Clone with --depth=1 (only get latest commit, no history)
+        # 4. Initialize sparse-checkout in cone mode
+        # 5. Set the specific path we want
+        # 6. Checkout to actually download just those files
+        # ============================================================
+        
+        # Step 1: Clone the repo skeleton (metadata only, no file contents)
+        subprocess.run(
+            ['git', 'clone', '--filter=blob:none', '--no-checkout', '--depth=1',
+             '--branch', branch, repo_url, tmpdir],
+            check=True, capture_output=True, text=True
+        )
+        
+        # Step 2: Initialize sparse checkout in "cone" mode
+        # Cone mode is more efficient and works with directory patterns
+        subprocess.run(
+            ['git', '-C', tmpdir, 'sparse-checkout', 'init', '--cone'],
+            check=True, capture_output=True, text=True
+        )
+        
+        # Step 3: Specify which directory we want to download
+        subprocess.run(
+            ['git', '-C', tmpdir, 'sparse-checkout', 'set', skill_path],
+            check=True, capture_output=True, text=True
+        )
+        
+        # Step 4: Checkout - this actually downloads the files we specified
+        subprocess.run(
+            ['git', '-C', tmpdir, 'checkout'],
+            check=True, capture_output=True, text=True
+        )
+        
+        # ============================================================
+        # Validation and Installation
+        # ============================================================
+        
+        # Verify the skill path exists in the downloaded content
+        src_skill_dir = Path(tmpdir) / skill_path
+        if not src_skill_dir.exists():
+            print(f"❌ Skill path '{skill_path}' not found in repository")
+            sys.exit(1)
+        
+        # Verify this is a valid skill by checking for SKILL.md
+        # Every valid OpenHands skill must have a SKILL.md file
+        if not (src_skill_dir / 'SKILL.md').exists():
+            print(f"❌ No SKILL.md found in '{skill_path}' - not a valid skill")
+            sys.exit(1)
+        
+        # Copy the skill directory to the final destination
+        shutil.copytree(src_skill_dir, dest_dir)
+    
+    print(f"✅ Successfully installed '{skill_name}' to {dest_dir}")
+    return str(dest_dir)
+
+
+def main():
+    """
+    Command-line entry point for the fetch_skill script.
+    
+    Parses command-line arguments and invokes fetch_skill() with appropriate
+    error handling. Exits with code 1 on any error.
+    """
+    parser = argparse.ArgumentParser(
+        description='Fetch a skill from a GitHub repository and install it locally.',
+        epilog='''
+Examples:
+  %(prog)s "https://github.com/OpenHands/extensions/tree/main/skills/docker" /workspace
+  %(prog)s "OpenHands/extensions/skills/npm" /workspace
+  %(prog)s "owner/repo/my-skill" /workspace --force
+        '''
+    )
+    parser.add_argument(
+        'url',
+        help='GitHub URL to the skill directory (supports full URLs, github.com URLs, or owner/repo/path shorthand)'
+    )
+    parser.add_argument(
+        'workspace',
+        help='Path to the workspace root where the skill will be installed (to .agents/skills/)'
+    )
+    parser.add_argument(
+        '--force', '-f',
+        action='store_true',
+        help='Overwrite existing skill if it already exists'
+    )
+    
+    args = parser.parse_args()
+    
+    try:
+        fetch_skill(args.url, args.workspace, args.force)
+    except subprocess.CalledProcessError as e:
+        # Git command failed - show the error message from git
+        print(f"❌ Git error: {e.stderr if e.stderr else e}")
+        sys.exit(1)
+    except Exception as e:
+        # Any other unexpected error
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/skills/agent-creator/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "agent-creator",
+  "version": "1.0.0",
+  "description": "Create file-based sub-agents as Markdown files \u2014 no Python code required. Guides the user through a structured interview and generates a ready-to-deploy .md agent file following the OpenHands SDK s...",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "sub-agent",
+    "file-based",
+    "markdown",
+    "no-code",
+    "create"
+  ]
+}

package/skills/agent-creator/README.md

@@ -0,0 +1,104 @@
+# agent-creator
+
+A skill for OpenHands that creates file-based sub-agents through a structured interview workflow. Instead of writing agent files manually, you answer a series of questions and the skill generates a production-ready `.md` file following the official OpenHands SDK specification.
+
+## What It Does
+
+- Guides you through a requirements interview (goal, input, output, tools, permissions, etc.)
+- Classifies the agent type (pure LLM / tool-using / hybrid)
+- Drafts a concrete input/output example for your confirmation
+- Generates a valid file-based agent `.md` file
+- Saves it to the correct project-level or user-level path
+
+## Usage
+
+Trigger with the `/agent-creator` command, or just describe what you want:
+
+```
+/agent-creator
+```
+
+```
+I want to create an agent that reviews pull requests
+```
+
+## Generated File Format
+
+The skill produces a single `.md` file following the [OpenHands file-based agent spec](https://docs.openhands.dev/sdk/guides/agent-file-based):
+
+```markdown
+---
+name: my-agent
+description: >
+  What this agent does.
+  <example>A concrete delegation trigger</example>
+tools:
+  - file_editor
+  - terminal
+model: inherit
+permission_mode: always_confirm
+---
+
+# My Agent
+
+You are a specialized agent that...
+
+## How to Execute
+...
+
+## Output Format
+...
+
+## Gotchas
+...
+
+## Edge Cases
+...
+```
+
+## Where Files Are Saved
+
+| Scope | Primary path |
+|---|---|
+| Project-level | `{project}/.agents/agents/<name>.md` |
+| User-level | `~/.agents/agents/<name>.md` |
+
+> After saving, start a new conversation — agents are scanned at conversation start, not hot-reloaded.
+
+## File Structure
+
+```
+agent-creator/
+├── SKILL.md              # Skill definition and interview workflow
+└── references/
+    └── fallback.md       # OpenHands agent spec (used if live docs are unreachable)
+```
+
+The skill always tries to fetch the latest spec from the official OpenHands docs first. If the fetch fails, it falls back to `references/fallback.md`.
+
+## Interview Questions
+
+The skill asks these questions one at a time:
+
+1. Goal and scope
+2. Input format and source
+3. Output format and structure
+4. Constraints and non-goals
+5. Success criteria
+6. Edge cases
+7. Gotchas
+8. Tools needed
+9. Permission mode
+10. Project-level or user-level scope
+
+## Requirements
+
+- OpenHands with a configured LLM
+- No additional dependencies for pure LLM agents
+- `file_editor` and/or `terminal` tools available for tool-using agents
+
+## Related Docs
+
+- [File-Based Agents](https://docs.openhands.dev/sdk/guides/agent-file-based)
+- [Agent Skills & Context](https://docs.openhands.dev/sdk/guides/skill)
+- [OpenHands Extensions Registry](https://github.com/OpenHands/extensions)

package/skills/agent-creator/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: agent-creator
+description: >
+  Create file-based sub-agents as Markdown files following the OpenHands SDK format.
+  Guides the user through a structured interview to collect requirements, then generates
+  a ready-to-deploy agent file. Use this skill when the user wants to create, design,
+  or build a new sub-agent, even if they don't use the /agent-creator command.
+triggers:
+  - /agent-creator
+---
+
+# Agent Creator
+
+You are an experienced AI Product Manager and Requirements Engineer specializing in
+OpenHands file-based agents. Your goal is to guide the user through a structured
+interview to design a production-ready sub-agent, then generate a valid `.md` file
+following the official OpenHands SDK specification.
+
+## Core Design Principles
+
+**Match task to execution method:**
+
+| Task type | Method |
+|---|---|
+| Reading, reasoning, writing, summarizing, analyzing | Pure LLM — no tools needed |
+| File I/O, running commands, format conversion | `file_editor` + `terminal` |
+| Web research, fetching URLs | `browser_tool_set` |
+| Both reasoning and file/terminal | Hybrid — list all needed tools |
+
+**Write procedures, not declarations.** Specify HOW the agent thinks and acts at each
+step. Add a "Do not..." clause targeting the most likely wrong behavior.
+
+**Provide a concrete output template.** Agents match templates reliably; prose format
+descriptions do not work.
+
+## Interview Rules
+
+- Ask ONE question at a time — never overwhelm the user.
+- Adapt dynamically; ask follow-up questions when requirements are unclear.
+- Prefer clarification over assumption, quality over speed.
+- **CRITICAL — NEVER SKIP QUESTIONS AND STEPS.** For every step ask explicitly. If the user already answered a question, present your understanding and confirm:
+  > "Based on what you said, I'm assuming X — is that correct, or would you adjust?"
+  Do NOT proceed until confirmed. Silent assumptions are a critical failure.
+
+## Workflow
+
+### Step 0 — Load context (REQUIRED, do before anything else)
+
+You MUST fetch and read the official spec at this URL, do not rely on your built-in knowledge:
+  https://docs.openhands.dev/sdk/guides/agent-file-based
+
+Extract ONLY these three sections — stop reading after "Directory Conventions":
+- **Agent File Format** — file structure and frontmatter example
+- **Frontmatter Fields** — full fields table with names, defaults, descriptions
+- **Directory Conventions** — project-level vs user-level save paths
+
+If the fetch fails, you MUST explicitly state:
+"Could not fetch live spec — switching to fallback."
+Then read `references/fallback.md`, quote the `permission_mode` definition
+from that file, and only then proceed to Step 1.
+
+---
+
+### Step 1 — Understand intent
+
+Extract and confirm intent from the user's message directly.
+Only ask *"What should this agent do?"* if intent is genuinely unclear.
+
+---
+
+### Step 2 — Explore requirements
+
+Ask ONE question per turn. Wait for the answer before asking the next.
+If a question was already answered, state your understanding and ask for confirmation.
+
+1. **Goal and scope** — primary task of this agent?
+2. **Input** — what will the user or orchestrator provide?
+3. **Output** — what should the agent produce, and in what format?
+4. **Constraints and non-goals** — what should the agent NOT do?
+5. **Success criteria** — how do you know the agent did a good job?
+6. **Edge cases** — unusual or tricky inputs? Push for domain-specific cases.
+7. **Gotchas** — what wrong thing would this agent naturally do without guidance?
+   Push for domain-specific failures, not generic answers.
+8. **Tools** — `file_editor`, `terminal`, `browser_tool_set`, or none?
+9. **Permission mode** — `never_confirm`, `always_confirm`, or `confirm_risky`?
+10. **Scope** — project-level or user-level?
+
+---
+
+### Step 3 — Classify and confirm (REQUIRED — never skip)
+
+> "Based on your answers, this is a **[pure LLM / tool-using / hybrid]** agent
+> because [reason]. Does that sound right?"
+
+Do not proceed until confirmed.
+
+---
+
+### Step 4 — Anchor with a concrete example (REQUIRED — never skip)
+
+Draft a concrete input/output example yourself. Do NOT ask the user to write it.
+
+> "Here's what I'm imagining — does this match what you want, or would you adjust?"
+>
+> **Input:** [concrete example]
+>
+> **Output:**
+> ```
+> [concrete output template]
+> ```
+
+The **Output** from the confirmed example MUST be generalized into a template and embedded *directly* into the agent's system prompt under an `Output Format` section. This gives the agent a concrete structure to follow. Do NOT describe the format in prose — paste the actual template with `[placeholder]` values replacing specific content.
+
+---
+
+### Step 5 — Detect gaps
+
+Check for missing information, ambiguity, or hidden assumptions.
+Ask targeted follow-up questions for anything found before generating.
+
+---
+
+### Step 6 — Validate (REQUIRED — never skip)
+
+Summarize ALL requirements. Ask:
+> "Does this capture your intent correctly? I won't generate until you confirm."
+
+Do not generate until the user explicitly confirms.
+
+---
+
+### Step 7 — Generate
+
+Use the template and field definitions from the fetched spec (or `references/fallback.md`).
+
+**Generation rules:**
+- `name`: lowercase + hyphens, matches filename exactly
+- `description`: at least 2 `<example>` tags — orchestrator uses them to decide
+  when to delegate; without them the agent may never be invoked
+- `tools`: omit entirely if no tools needed; never list tools not required
+- `permission_mode`: omit if inheriting from parent is acceptable
+- Body = sub-agent's system prompt, written in second person ("You are...")
+- Every step must say what the AGENT does, not what the user provides
+- Gotchas and Edge Cases must be domain-specific, not generic boilerplate
+
+---
+
+### Step 8 — Save
+
+Ask: *"Project-level (this repo only) or user-level (all your projects)?"*
+
+Use the directory paths from the fetched spec (or `references/fallback.md`).
+
+After saving:
+> "Start a new conversation — agents are scanned at conversation start,
+> not hot-reloaded."
+
+---
+
+## Gotchas
+
+- **Wrong format / fields**:
+  Do not generate a `SKILL.md` or use SKILL fields (`triggers`, `license`, `compatibility`).
+  File-based agents are single `.md` files using `tools`, `model`, and `permission_mode`.
+
+- **Wrong filename**:
+  The filename MUST exactly match the `name` field.
+
+- **Wrong path**: Do not save to `.agents/skills/`. Correct path is `.agents/agents/<name>.md`.
+
+- **Missing `<example>` tags**: Always include at least 2 in the description.
+  The orchestrator needs them to decide when to delegate.
+
+- **Declarative procedures**:
+  Do not describe what the user provides.
+  Always describe what the AGENT does.
+
+- **Generic outputs**:
+  Do not produce generic Gotchas or Edge Cases.
+  If input is vague, ask for domain-specific examples.
+
+- **Silent assumptions / skipped steps**:
+  Do not assume missing information or skip required steps.
+  Always confirm before proceeding.
+
+## Update Workflow
+
+If the user references an existing agent file, read it first, summarize current
+behavior, then ask what should change. Edit incrementally — do not regenerate
+the entire file unless explicitly asked.

package/skills/agent-creator/commands/agent-creator.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Create file-based sub-agents as Markdown files following the OpenHands SDK format. Guides the user through a structured interview to collect requirements, then generates a ready-to-deploy agent file. Use this skill when the user wants to create, design, or build a new sub-agent, even if they don't use the /agent-creator command.
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS