@openhands/extensions 0.0.1-alpha → 0.2.0

package/scripts/sync_openhands_sdk_skill.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Auto-generate skills/openhands-sdk/SKILL.md from live data sources.
+
+Data sources:
+  1. https://docs.openhands.dev/llms.txt  - SDK doc index
+  2. GitHub API for OpenHands/software-agent-sdk - examples + hello world
+
+Usage:
+  python scripts/sync_openhands_sdk_skill.py           # regenerate SKILL.md
+  python scripts/sync_openhands_sdk_skill.py --check   # CI mode: fail if stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import os
+import re
+import sys
+import textwrap
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+SKILL_PATH = Path(__file__).resolve().parent.parent / "skills" / "openhands-sdk" / "SKILL.md"
+LLMS_TXT_URL = "https://docs.openhands.dev/llms.txt"
+GH_API = "https://api.github.com/repos/OpenHands/software-agent-sdk/contents/examples"
+GH_RAW = "https://raw.githubusercontent.com/OpenHands/software-agent-sdk/main"
+GH_BROWSE = "https://github.com/OpenHands/software-agent-sdk/blob/main/examples"
+GH_TREE = "https://github.com/OpenHands/software-agent-sdk/tree/main/examples"
+HELLO_WORLD = f"{GH_RAW}/examples/01_standalone_sdk/01_hello_world.py"
+
+FRONTMATTER = """\
+---
+name: openhands-sdk
+description: >-
+  Reference skill for the OpenHands Software Agent SDK - the Python framework
+  for building AI agents that write software. Use when you need to build agents
+  with the SDK, create custom tools, configure LLMs, manage conversations,
+  delegate to sub-agents, or deploy agents locally or remotely.
+triggers:
+- openhands-sdk
+- openhands sdk
+- software-agent-sdk
+- agent-sdk
+- /sdk
+---"""
+
+# Maps llms.txt arch-page title -> class name shown in the table.
+ARCH_CLASS_MAP = {
+    "Agent": "Agent",
+    "LLM": "LLM",
+    "Conversation": "Conversation",
+    "Events": "Event",
+    "Skill": "Skill",
+    "Condenser": "Condenser",
+    "Security": "SecurityAnalyzer",
+    "Tool System & MCP": "Tool / ToolDefinition",
+    "Workspace": "Workspace",
+}
+
+_ENTRY_RE = re.compile(r"^- \[(?P<title>[^\]]+)\]\((?P<url>[^)]+)\):\s*(?P<desc>.+)$")
+
+
+# -- network --
+
+def _fetch(url: str, accept: str = "text/plain") -> str:
+    headers = {"Accept": accept, "User-Agent": "sync-sdk-skill/1.0"}
+    token = os.environ.get("GITHUB_TOKEN")
+    if token and "api.github.com" in url:
+        headers["Authorization"] = f"token {token}"
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return resp.read().decode()
+
+
+def _fetch_json(url: str) -> list | dict:
+    return json.loads(_fetch(url, accept="application/vnd.github.v3+json"))
+
+
+def _fetch_or(url: str, fallback, **kw):
+    try:
+        return _fetch(url, **kw) if "accept" not in kw else _fetch(url, **kw)
+    except Exception as e:
+        print(f"WARNING: {e} — using fallback", file=sys.stderr)
+        return fallback
+
+
+# -- llms.txt parsing --
+
+def parse_sdk_entries(llms_txt: str) -> list[dict]:
+    """Extract entries from the 'OpenHands Software Agent SDK' section."""
+    entries, in_section = [], False
+    for line in llms_txt.splitlines():
+        stripped = line.strip()
+        if stripped == "## OpenHands Software Agent SDK":
+            in_section = True
+            continue
+        if in_section and line.startswith("## "):
+            break
+        if in_section and (m := _ENTRY_RE.match(stripped)):
+            entries.append(m.groupdict())
+    return entries
+
+
+# -- content builders --
+
+def build_classes_table(entries: list[dict]) -> str:
+    lines = ["| Class | Purpose |", "|---|---|"]
+    for e in entries:
+        if "/arch/" not in e["url"]:
+            continue
+        class_name = ARCH_CLASS_MAP.get(e["title"])
+        if not class_name:
+            continue
+        desc = re.sub(r"^High-level architecture of (the )?", "", e["desc"])
+        desc = desc[0].upper() + desc[1:]
+        lines.append(f"| [`{class_name}`]({e['url']}) | {desc} |")
+    return "\n".join(lines)
+
+
+def build_api_refs(entries: list[dict]) -> str:
+    return ", ".join(
+        f"[`{e['title']}`]({e['url']})"
+        for e in entries if "/api-reference/" in e["url"]
+    )
+
+
+def build_guides(entries: list[dict]) -> str:
+    return "\n".join(
+        f"- [{e['title']}]({e['url']}): {e['desc']}"
+        for e in entries
+        if "/api-reference/" not in e["url"] and "/arch/" not in e["url"]
+    )
+
+
+def build_examples(categories: dict[str, list[dict]]) -> str:
+    lines = [f"Source: [`examples/`]({GH_TREE})", ""]
+    for dir_name, items in categories.items():
+        lines.append(f"### [`{dir_name}/`]({GH_TREE}/{dir_name})")
+        lines.append("")
+        for item in sorted(items, key=lambda x: x["name"]):
+            name = item["name"]
+            if name.startswith(".") or name == "__pycache__":
+                continue
+            prefix = GH_TREE if item.get("type") == "dir" else GH_BROWSE
+            lines.append(f"- [`{name}`]({prefix}/{dir_name}/{name})")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def fetch_examples() -> dict[str, list[dict]]:
+    top = _fetch_json(GH_API)
+    categories: dict[str, list[dict]] = {}
+    for item in sorted(top, key=lambda x: x["name"]):
+        if item["type"] != "dir":
+            continue
+        try:
+            categories[item["name"]] = _fetch_json(f"{GH_API}/{item['name']}")
+        except Exception as e:
+            print(f"WARNING: examples/{item['name']}: {e}", file=sys.stderr)
+    return categories
+
+
+# -- generate --
+
+HELLO_WORLD_FALLBACK = textwrap.dedent("""\
+    import os
+    from openhands.sdk import LLM, Agent, Conversation, Tool
+    from openhands.tools.terminal import TerminalTool
+    from openhands.tools.file_editor import FileEditorTool
+
+    llm = LLM(model="anthropic/claude-sonnet-4-5-20250929", api_key=os.getenv("LLM_API_KEY"))
+    agent = Agent(llm=llm, tools=[Tool(name=TerminalTool.name), Tool(name=FileEditorTool.name)])
+    conversation = Conversation(agent=agent, workspace=os.getcwd())
+    conversation.send_message("Hello!")
+    conversation.run()""")
+
+
+def generate() -> str:
+    print("Fetching llms.txt ...", file=sys.stderr)
+    llms_txt = _fetch(LLMS_TXT_URL)
+    entries = parse_sdk_entries(llms_txt)
+
+    print("Fetching examples ...", file=sys.stderr)
+    try:
+        examples = fetch_examples()
+    except Exception:
+        examples = {}
+
+    print("Fetching hello world ...", file=sys.stderr)
+    hello = _fetch_or(HELLO_WORLD, HELLO_WORLD_FALLBACK).strip()
+
+    return f"""{FRONTMATTER}
+
+# OpenHands Software Agent SDK
+
+All SDK documentation lives at <https://docs.openhands.dev/sdk>.
+
+For the full topic index, fetch <https://docs.openhands.dev/llms.txt> and read
+the "OpenHands Software Agent SDK" section.
+
+## Quick reference
+
+Install: `pip install openhands-sdk openhands-tools`
+
+```python
+{hello}
+```
+
+## Core classes (`openhands.sdk`)
+
+{build_classes_table(entries)}
+
+## API reference
+
+{build_api_refs(entries)}
+
+## Guides
+
+{build_guides(entries)}
+
+## Examples
+
+{build_examples(examples)}
+"""
+
+
+# -- main --
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="CI mode: fail if stale")
+    args = parser.parse_args()
+
+    generated = generate()
+
+    if args.check:
+        current = SKILL_PATH.read_text() if SKILL_PATH.exists() else ""
+        if current == generated:
+            print("SDK skill is up to date. ✓", file=sys.stderr)
+            return 0
+        diff = difflib.unified_diff(
+            current.splitlines(keepends=True),
+            generated.splitlines(keepends=True),
+            fromfile="current SKILL.md",
+            tofile="generated SKILL.md",
+        )
+        sys.stdout.writelines(diff)
+        print(
+            "\nERROR: SDK skill is out of date. "
+            "Run: python scripts/sync_openhands_sdk_skill.py",
+            file=sys.stderr,
+        )
+        return 1
+
+    SKILL_PATH.write_text(generated)
+    print(f"Wrote {SKILL_PATH}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/README.md

@@ -0,0 +1,159 @@
+# OpenHands Skills
+
+Skills are specialized prompts that enhance OpenHands with domain-specific knowledge and task-specific workflows. They help developers by providing expert guidance, automating common tasks, and ensuring consistent practices across projects. Each skill is designed to excel in a specific area, from Git operations to code review processes.
+
+## Terminology Note
+
+**Version 0 (V0)**: The term "skills" continues to be used for V0 conversations. V0 is the current stable version of OpenHands.
+
+**Version 1 (V1)**: The term "skills" is used for V1 conversations. V1 UI and app server have not yet been released, but the codebase has been updated to use "skills" terminology in preparation for the V1 release.
+
+This directory (`OpenHands/extensions/`) contains shareable skills that will be used in V1 conversations. For V0 conversations, the system continues to use skills from the same underlying files.
+
+## Sources of Skills
+
+OpenHands loads skills (V1) or skills (V0) from two sources:
+
+### 1. Shareable Skills (Public)
+
+This directory (`OpenHands/extensions/`) contains shareable skills (V1) or skills (V0) that are:
+
+- Available to all OpenHands users
+- Maintained in the OpenHands repository
+- Perfect for reusable knowledge and common workflows
+- Used as "skills" in V1 conversations and "skills" in V0 conversations
+
+Directory structure:
+
+```
+OpenHands/extensions/
+├── # Keyword-triggered expertise
+│   ├── git.md         # Git operations
+│   ├── testing.md     # Testing practices
+│   └── docker.md      # Docker guidelines
+└── # These skills are always loaded
+    ├── pr_review.md   # PR review process
+    ├── bug_fix.md     # Bug fixing workflow
+    └── feature.md     # Feature implementation
+```
+
+### 2. Repository Instructions (Private)
+
+Each repository can have its own instructions. On V1, use `.agents/skills/`. For backward compatibility, `.openhands/skills/` and `.openhands/microagents/` are still supported. These instructions are:
+
+- Private to that repository
+- Automatically loaded when working with that repository
+- Perfect for repository-specific guidelines and team practices
+
+Example repository structure:
+
+```
+your-repository/
+├── .agents/
+│   └── skills/        # V1: Preferred location for repository-specific skills
+│       └── repo.md    # Repository-specific instructions
+│       └── ...        # Private skills that are only available inside this repo
+└── .openhands/         # Legacy locations (still supported)
+    ├── skills/         # Legacy V1 path
+    │   └── repo.md
+    └── microagents/    # Legacy V0 path
+        └── repo.md
+```
+
+## Loading Order
+
+When OpenHands works with a repository, it:
+
+1. Loads repository-specific instructions from `.agents/skills/` (V1) if present
+2. Also checks `.openhands/skills/` and `.openhands/microagents/` for backward compatibility
+3. Loads relevant knowledge agents based on keywords in conversations
+
+## Types of Skills
+
+Most skills use markdown files with YAML frontmatter. For repository agents (repo.md), the frontmatter is optional - if not provided, the file will be loaded with default settings as a repository agent.
+
+### 1. Knowledge Agents
+
+Knowledge agents provide specialized expertise that's triggered by keywords in conversations. They help with:
+
+- Language best practices
+- Framework guidelines
+- Common patterns
+- Tool usage
+
+Key characteristics:
+
+- **Trigger-based**: Activated by specific keywords in conversations
+- **Context-aware**: Provide relevant advice based on file types and content
+- **Reusable**: Knowledge can be applied across multiple projects
+- **Versioned**: Support multiple versions of tools/frameworks
+
+You can see an example of a knowledge-based agent in [OpenHands's github skill](https://github.com/OpenHands/OpenHands/tree/main/skills/github.md).
+
+### 2. Repository Agents
+
+Repository agents provide repository-specific knowledge and guidelines. They are:
+
+- Loaded from `.openhands/microagents/repo.md` (V0) or `.agents/skills/` directory (V1)
+- Specific to individual repositories
+- Automatically activated for their repository
+- Perfect for team practices and project conventions
+
+Key features:
+
+- **Project-specific**: Contains guidelines unique to the repository
+- **Team-focused**: Enforces team conventions and practices
+- **Always active**: Automatically loaded for the repository
+- **Locally maintained**: Updated with the project
+
+You can see an example of a repo agent in [the agent for the OpenHands repo itself](https://github.com/OpenHands/OpenHands/blob/main/.agents/skills/repo.md).
+
+## Contributing
+
+### When to Contribute
+
+1. **Knowledge Agents** - When you have:
+
+   - Language/framework best practices
+   - Tool usage patterns
+   - Common problem solutions
+   - General development guidelines
+
+2. **Repository Agents** - When you need:
+   - Project-specific guidelines
+   - Team conventions and practices
+   - Custom workflow documentation
+   - Repository-specific setup instructions
+
+### Best Practices
+
+1. **For Knowledge Agents**:
+
+   - Choose distinctive triggers
+   - Focus on one area of expertise
+   - Include practical examples
+   - Use file patterns when relevant
+   - Keep knowledge general and reusable
+
+2. **For Repository Agents**:
+   - Document clear setup instructions
+   - Include repository structure details
+   - Specify testing and build procedures
+   - List environment requirements
+   - Document CI workflows and checks
+   - Include information about code quality standards
+   - Maintain up-to-date team practices
+   - Consider using OpenHands to generate a comprehensive repo.md (see [Creating a Repository Agent](#creating-a-repository-agent))
+   - YAML frontmatter is optional - files without frontmatter will be loaded with default settings
+
+### Submission Process
+
+1. Create your agent file in the appropriate directory:
+   - `skills/` for expertise (public, shareable)
+   - Note: Repository-specific agents should remain in their respective repositories' `.agents/skills/` (V1) or `.openhands/microagents/` (V0) directory
+2. Test thoroughly
+3. Submit a pull request to OpenHands
+
+## License
+
+All skills are subject to the same license as OpenHands. See the root LICENSE file for details.

package/skills/add-javadoc/.plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "add-javadoc",
+  "version": "1.0.0",
+  "description": "Add comprehensive JavaDoc documentation to Java classes and methods. Use when documenting Java code, adding API documentation, or improving code documentation.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "javadoc",
+    "java",
+    "documentation",
+    "api-docs"
+  ]
+}

package/skills/add-javadoc/README.md

@@ -0,0 +1,40 @@
+# add-javadoc
+
+Add comprehensive JavaDoc documentation to Java classes and methods. Use when documenting Java code, adding API documentation, or improving code documentation.
+
+## Triggers
+
+This skill is activated by the following keywords:
+
+- `javadoc`
+- `java documentation`
+- `document java`
+
+## Details
+
+This skill guides the agent to add standard JavaDoc comments to all public classes and methods in Java source files.
+
+### Class-Level Documentation
+
+For each public class, the agent will:
+- Add a class-level JavaDoc block describing the purpose and responsibility of the class
+- Include an `@author` tag if appropriate
+
+### Method-Level Documentation
+
+For each public method, the agent will:
+- Add a method-level JavaDoc block describing what the method does
+- Include `@param` tags for all parameters with clear descriptions
+- Include a `@return` tag describing the return value
+- Include `@throws` tags for any checked exceptions
+
+### Style Guidelines
+
+- First sentence should be a concise summary
+- Use HTML tags sparingly (prefer plain text)
+- Document preconditions and postconditions when relevant
+- Include code examples with `{@code ...}` for complex methods
+
+## Example
+
+See [references/example.md](references/example.md) for a before/after example showing undocumented Java code transformed with proper JavaDoc comments.

package/skills/add-javadoc/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: add-javadoc
+description: Add comprehensive JavaDoc documentation to Java classes and methods. Use when documenting Java code, adding API documentation, or improving code documentation.
+license: MIT
+compatibility: Requires Java source files
+triggers:
+  - javadoc
+  - java documentation
+  - document java
+---
+
+Add comprehensive JavaDoc documentation to all public classes and methods.
+
+## Class-Level Documentation
+
+For each public class:
+- Add class-level JavaDoc describing the purpose and responsibility of the class
+- Include `@author` tag if appropriate
+
+## Method-Level Documentation
+
+For each public method:
+- Add method-level JavaDoc describing what the method does
+- Include `@param` tags for all parameters with clear descriptions
+- Include `@return` tag describing the return value
+- Include `@throws` tags for any checked exceptions
+
+## Style Guidelines
+
+- First sentence should be a concise summary
+- Use HTML tags sparingly (prefer plain text)
+- Document preconditions and postconditions when relevant
+- Include code examples with `{@code ...}` for complex methods
+
+See [references/example.md](references/example.md) for before/after examples.

package/skills/add-javadoc/references/example.md

@@ -0,0 +1,32 @@
+# JavaDoc Example
+
+## Before
+
+```java
+public class UserService {
+    public User findById(String id) {
+        return repository.find(id);
+    }
+}
+```
+
+## After
+
+```java
+/**
+ * Service for managing user operations.
+ *
+ * @author Generated by Large Codebase SDK
+ */
+public class UserService {
+    /**
+     * Finds a user by their unique identifier.
+     *
+     * @param id The unique identifier of the user
+     * @return The User object if found, null otherwise
+     */
+    public User findById(String id) {
+        return repository.find(id);
+    }
+}
+```

package/skills/add-skill/.plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "add-skill",
+  "version": "1.0.0",
+  "description": "Add (import) an OpenHands skill from a GitHub repository into the current workspace.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "skill",
+    "import",
+    "github",
+    "sparse-checkout"
+  ]
+}

package/skills/add-skill/README.md

@@ -0,0 +1,67 @@
+# add-skill
+
+Add (import) an OpenHands skill from a GitHub repository into the current workspace.
+
+This skill is useful when a user says things like:
+
+- “Add the `codereview` skill from https://github.com/OpenHands/extensions/”
+- “/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview”
+
+It fetches only the requested skill directory (via git sparse checkout) and installs it into the workspace so OpenHands can use it.
+
+## What it does
+
+- Parses a GitHub URL (multiple formats supported)
+- Downloads only the requested skill folder (no full repo clone)
+- Validates the downloaded folder contains a `SKILL.md`
+- Installs the skill into:
+
+```text
+<workspace>/.agents/skills/<skill-name>/
+```
+
+## Included files
+
+- `SKILL.md` – skill metadata + usage guidance for the agent
+- `scripts/fetch_skill.py` – implementation used to fetch/install a skill
+
+## Usage
+
+From the `add-skill` skill directory:
+
+```bash
+python3 scripts/fetch_skill.py "<github-skill-url>" "<workspace-path>" [--force]
+```
+
+### Examples
+
+```bash
+# Full URL with explicit branch
+python3 scripts/fetch_skill.py \
+  "https://github.com/OpenHands/extensions/tree/main/skills/docker" \
+  "/workspace"
+
+# Shorthand form (defaults to main)
+python3 scripts/fetch_skill.py \
+  "OpenHands/extensions/skills/codereview" \
+  "/workspace"
+
+# Overwrite if the skill already exists
+python3 scripts/fetch_skill.py \
+  "OpenHands/extensions/tree/main/skills/codereview" \
+  "/workspace" \
+  --force
+```
+
+## Supported URL formats
+
+- `https://github.com/<owner>/<repo>/tree/<branch>/<path/to/skill>`
+- `https://github.com/<owner>/<repo>/<path/to/skill>` (defaults to `main`)
+- `github.com/<owner>/<repo>/<path/to/skill>`
+- `<owner>/<repo>/<path/to/skill>`
+
+## Notes / caveats
+
+- If `GITHUB_TOKEN` is set, it will be used for authentication (needed for private repos).
+- If the destination already exists, the script will fail unless `--force` is provided.
+- The script installs under `.agents/skills/`.

package/skills/add-skill/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: add-skill
+description: Add an external skill from a GitHub repository to the current workspace. Use when users want to import, install, or add a skill from a GitHub URL (e.g., `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview` or "add the codereview skill from https://github.com/OpenHands/extensions/"). Handles fetching the skill files and placing them in .agents/skills/.
+---
+
+# Add Skill
+
+Import skills from GitHub repositories into the current workspace.
+
+## Workflow
+
+When a user requests to add a skill from a GitHub URL:
+
+1. **Parse the URL** to extract repository owner, name, and skill path
+2. **Fetch the skill** using the bundled script:
+   ```bash
+   python3 <this-skill-path>/scripts/fetch_skill.py "<github-url>" "<workspace-path>"
+   ```
+3. **Verify** that SKILL.md exists in the destination
+4. **Inform the user** the skill is now available
+
+## URL Formats Supported
+
+- `https://github.com/owner/repo/tree/main/path/to/skill`
+- `https://github.com/owner/repo/skill-name`
+- `github.com/owner/repo/skill-name`
+- `owner/repo/skill-name` (shorthand)
+
+## Example
+
+User: `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview`
+
+```bash
+# Run the fetch script
+python3 scripts/fetch_skill.py "https://github.com/OpenHands/extensions/tree/main/skills/codereview" "/path/to/workspace"
+
+# Verify installation
+ls /path/to/workspace/.agents/skills/codereview/SKILL.md
+```
+
+Response: "✅ Added `codereview` to your workspace. The skill is now available."
+
+## Notes
+
+- Creates `.agents/skills/` directory if it doesn't exist
+- Uses `GITHUB_TOKEN` for authentication (required for private repos)
+- Warns before overwriting existing skills with the same name