From f8eaf7bd504adf0012fd55c020a2cd9777213898 Mon Sep 17 00:00:00 2001 From: sck_0 Date: Fri, 16 Jan 2026 16:09:39 +0100 Subject: [PATCH] feat: add 7 new skills from GitHub repo analysis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New skills: - prompt-library: Curated role-based and task-specific prompt templates - javascript-mastery: 33+ essential JavaScript concepts - llm-app-patterns: RAG pipelines, agent architectures, LLMOps - workflow-automation: Multi-step automation and API integration - autonomous-agent-patterns: Tool design, permissions, browser automation - bun-development: Bun runtime, testing, bundling, Node.js migration - github-workflow-automation: AI PR reviews, issue triage, CI/CD Sources: n8n, awesome-chatgpt-prompts, dify, gemini-cli, bun, 33-js-concepts, cline, codex Total skills: 62 → 69 --- README.md | 95 +-- skills/autonomous-agent-patterns/SKILL.md | 761 ++++++++++++++++++ skills/bun-development/SKILL.md | 691 +++++++++++++++++ skills/github-workflow-automation/SKILL.md | 846 +++++++++++++++++++++ skills/javascript-mastery/SKILL.md | 645 ++++++++++++++++ skills/llm-app-patterns/SKILL.md | 760 ++++++++++++++++++ skills/prompt-library/SKILL.md | 322 ++++++++ skills/workflow-automation/SKILL.md | 705 +++++++++++++++++ skills_index.json | 44 +- 9 files changed, 4824 insertions(+), 45 deletions(-) create mode 100644 skills/autonomous-agent-patterns/SKILL.md create mode 100644 skills/bun-development/SKILL.md create mode 100644 skills/github-workflow-automation/SKILL.md create mode 100644 skills/javascript-mastery/SKILL.md create mode 100644 skills/llm-app-patterns/SKILL.md create mode 100644 skills/prompt-library/SKILL.md create mode 100644 skills/workflow-automation/SKILL.md diff --git a/README.md b/README.md index b145968d..94c1447e 100644 --- a/README.md +++ b/README.md @@ -36,55 +36,62 @@ The repository is organized into several key areas of expertise: --- -## Full Skill Registry (62/62) +## Full Skill Registry (69/69) Below is the complete list of available skills. Each skill folder contains a `SKILL.md` that can be imported into Antigravity or Claude Code. > [!NOTE] > **Document Skills**: We provide both **community** and **official Anthropic** versions for DOCX, PDF, PPTX, and XLSX. Locally, the official versions are used by default (via symlinks). In the repository, both versions are available for flexibility. -| Skill Name | Description | Path | -| :------------------------------- | :------------------------------------------------------------ | :--------------------------------------------- | -| **Algorithmic Art** | Creative generative art using p5.js and seeded randomness. | `skills/algorithmic-art` | -| **App Store Optimization** | Complete ASO toolkit for iOS and Android app performance. | `skills/app-store-optimization` | -| **AWS Pentesting** | Specialized security assessment for Amazon Web Services. | `skills/aws-penetration-testing` | -| **Backend Guidelines** | Core architecture patterns for Node/Express microservices. | `skills/backend-dev-guidelines` | -| **Brainstorming** | Requirement discovery and intent exploration framework. | `skills/brainstorming` | -| **Brand Guidelines (Anthropic)** | Official Anthropic brand styling and visual standards. | `skills/brand-guidelines-anthropic` ⭐ NEW | -| **Brand Guidelines (Community)** | Community-contributed brand guidelines and templates. | `skills/brand-guidelines-community` | -| **Canvas Design** | Beautiful static visual design in PDF and PNG. | `skills/canvas-design` | -| **Claude D3.js** | Advanced data visualization with D3.js. | `skills/claude-d3js-skill` | -| **Content Creator** | SEO-optimized marketing and brand voice toolkit. | `skills/content-creator` | -| **Core Components** | Design system tokens and baseline UI patterns. | `skills/core-components` | -| **Doc Co-authoring** | Structured workflow for technical documentation. | `skills/doc-coauthoring` | -| **DOCX (Official)** | Official Anthropic MS Word document manipulation. | `skills/docx-official` ⭐ NEW | -| **Ethical Hacking** | Comprehensive penetration testing lifecycle methodology. | `skills/ethical-hacking-methodology` | -| **Frontend Design** | Production-grade UI component implementation. | `skills/frontend-design` | -| **Frontend Guidelines** | Modern React/TS development patterns and file structure. | `skills/frontend-dev-guidelines` | -| **Git Pushing** | Automated staging and conventional commits. | `skills/git-pushing` | -| **Internal Comms (Anthropic)** | Official Anthropic corporate communication templates. | `skills/internal-comms-anthropic` ⭐ NEW | -| **Internal Comms (Community)** | Community-contributed communication templates. | `skills/internal-comms-community` | -| **Kaizen** | Continuous improvement and error-proofing (Poka-Yoke). | `skills/kaizen` | -| **Linux Shell Scripting** | Production-ready shell scripts for automation. | `skills/linux-shell-scripting` | -| **Loki Mode** | Fully autonomous startup development engine. | `skills/loki-mode` | -| **MCP Builder** | High-quality Model Context Protocol (MCP) server creation. | `skills/mcp-builder` | -| **NotebookLM** | Source-grounded querying via Google NotebookLM. | `skills/notebooklm` | -| **PDF (Official)** | Official Anthropic PDF document manipulation. | `skills/pdf-official` ⭐ NEW | -| **Pentest Checklist** | Structured security assessment planning and scoping. | `skills/pentest-checklist` | -| **PPTX (Official)** | Official Anthropic PowerPoint manipulation. | `skills/pptx-official` ⭐ NEW | -| **Product Toolkit** | RICE prioritization and product discovery frameworks. | `skills/product-manager-toolkit` | -| **Prompt Engineering** | Expert patterns for LLM instruction optimization. | `skills/prompt-engineering` | -| **React Best Practices** | Vercel's 40+ performance optimization rules for React. | `skills/react-best-practices` ⭐ NEW (Vercel) | -| **React UI Patterns** | Standardized loading states and error handling for React. | `skills/react-ui-patterns` | -| **Senior Architect** | Scalable system design and architecture diagrams. | `skills/senior-architect` | -| **Skill Creator** | Meta-skill for building high-performance agentic skills. | `skills/skill-creator` | -| **Software Architecture** | Quality-focused design principles and analysis. | `skills/software-architecture` | -| **Systematic Debugging** | Root cause analysis and structured fix verification. | `skills/systematic-debugging` | -| **TDD** | Test-Driven Development workflow and red-green-refactor. | `skills/test-driven-development` | -| **UI/UX Pro Max** | Advanced design intelligence and 50+ styling options. | `skills/ui-ux-pro-max` | -| **Web Artifacts** | Complex React/Tailwind/Shadcn UI artifact builder. | `skills/web-artifacts-builder` | -| **Web Design Guidelines** | Vercel's 100+ UI/UX audit rules (accessibility, performance). | `skills/web-design-guidelines` ⭐ NEW (Vercel) | -| **Webapp Testing** | Local web application testing with Playwright. | `skills/webapp-testing` | -| **XLSX (Official)** | Official Anthropic Excel spreadsheet manipulation. | `skills/xlsx-official` ⭐ NEW | +| Skill Name | Description | Path | +| :------------------------------- | :------------------------------------------------------------- | :--------------------------------------------- | +| **Algorithmic Art** | Creative generative art using p5.js and seeded randomness. | `skills/algorithmic-art` | +| **App Store Optimization** | Complete ASO toolkit for iOS and Android app performance. | `skills/app-store-optimization` | +| **Autonomous Agent Patterns** | Design patterns for autonomous coding agents and tools. | `skills/autonomous-agent-patterns` ⭐ NEW | +| **AWS Pentesting** | Specialized security assessment for Amazon Web Services. | `skills/aws-penetration-testing` | +| **Backend Guidelines** | Core architecture patterns for Node/Express microservices. | `skills/backend-dev-guidelines` | +| **Brainstorming** | Requirement discovery and intent exploration framework. | `skills/brainstorming` | +| **Brand Guidelines (Anthropic)** | Official Anthropic brand styling and visual standards. | `skills/brand-guidelines-anthropic` ⭐ NEW | +| **Brand Guidelines (Community)** | Community-contributed brand guidelines and templates. | `skills/brand-guidelines-community` | +| **Bun Development** | Modern JavaScript/TypeScript development with Bun runtime. | `skills/bun-development` ⭐ NEW | +| **Canvas Design** | Beautiful static visual design in PDF and PNG. | `skills/canvas-design` | +| **Claude D3.js** | Advanced data visualization with D3.js. | `skills/claude-d3js-skill` | +| **Content Creator** | SEO-optimized marketing and brand voice toolkit. | `skills/content-creator` | +| **Core Components** | Design system tokens and baseline UI patterns. | `skills/core-components` | +| **Doc Co-authoring** | Structured workflow for technical documentation. | `skills/doc-coauthoring` | +| **DOCX (Official)** | Official Anthropic MS Word document manipulation. | `skills/docx-official` ⭐ NEW | +| **Ethical Hacking** | Comprehensive penetration testing lifecycle methodology. | `skills/ethical-hacking-methodology` | +| **Frontend Design** | Production-grade UI component implementation. | `skills/frontend-design` | +| **Frontend Guidelines** | Modern React/TS development patterns and file structure. | `skills/frontend-dev-guidelines` | +| **Git Pushing** | Automated staging and conventional commits. | `skills/git-pushing` | +| **GitHub Workflow Automation** | AI-powered PR reviews, issue triage, and CI/CD integration. | `skills/github-workflow-automation` ⭐ NEW | +| **Internal Comms (Anthropic)** | Official Anthropic corporate communication templates. | `skills/internal-comms-anthropic` ⭐ NEW | +| **Internal Comms (Community)** | Community-contributed communication templates. | `skills/internal-comms-community` | +| **JavaScript Mastery** | 33+ essential JavaScript concepts every developer should know. | `skills/javascript-mastery` ⭐ NEW | +| **Kaizen** | Continuous improvement and error-proofing (Poka-Yoke). | `skills/kaizen` | +| **Linux Shell Scripting** | Production-ready shell scripts for automation. | `skills/linux-shell-scripting` | +| **LLM App Patterns** | RAG pipelines, agent architectures, and LLMOps patterns. | `skills/llm-app-patterns` ⭐ NEW | +| **Loki Mode** | Fully autonomous startup development engine. | `skills/loki-mode` | +| **MCP Builder** | High-quality Model Context Protocol (MCP) server creation. | `skills/mcp-builder` | +| **NotebookLM** | Source-grounded querying via Google NotebookLM. | `skills/notebooklm` | +| **PDF (Official)** | Official Anthropic PDF document manipulation. | `skills/pdf-official` ⭐ NEW | +| **Pentest Checklist** | Structured security assessment planning and scoping. | `skills/pentest-checklist` | +| **PPTX (Official)** | Official Anthropic PowerPoint manipulation. | `skills/pptx-official` ⭐ NEW | +| **Product Toolkit** | RICE prioritization and product discovery frameworks. | `skills/product-manager-toolkit` | +| **Prompt Engineering** | Expert patterns for LLM instruction optimization. | `skills/prompt-engineering` | +| **Prompt Library** | Curated role-based and task-specific prompt templates. | `skills/prompt-library` ⭐ NEW | +| **React Best Practices** | Vercel's 40+ performance optimization rules for React. | `skills/react-best-practices` ⭐ NEW (Vercel) | +| **React UI Patterns** | Standardized loading states and error handling for React. | `skills/react-ui-patterns` | +| **Senior Architect** | Scalable system design and architecture diagrams. | `skills/senior-architect` | +| **Skill Creator** | Meta-skill for building high-performance agentic skills. | `skills/skill-creator` | +| **Software Architecture** | Quality-focused design principles and analysis. | `skills/software-architecture` | +| **Systematic Debugging** | Root cause analysis and structured fix verification. | `skills/systematic-debugging` | +| **TDD** | Test-Driven Development workflow and red-green-refactor. | `skills/test-driven-development` | +| **UI/UX Pro Max** | Advanced design intelligence and 50+ styling options. | `skills/ui-ux-pro-max` | +| **Web Artifacts** | Complex React/Tailwind/Shadcn UI artifact builder. | `skills/web-artifacts-builder` | +| **Web Design Guidelines** | Vercel's 100+ UI/UX audit rules (accessibility, performance). | `skills/web-design-guidelines` ⭐ NEW (Vercel) | +| **Webapp Testing** | Local web application testing with Playwright. | `skills/webapp-testing` | +| **Workflow Automation** | Multi-step automations, API integration, AI-native pipelines. | `skills/workflow-automation` ⭐ NEW | +| **XLSX (Official)** | Official Anthropic Excel spreadsheet manipulation. | `skills/xlsx-official` ⭐ NEW | > [!TIP] > Use the `validate_skills.py` script in the `scripts/` directory to ensure all skills are properly formatted and ready for use. diff --git a/skills/autonomous-agent-patterns/SKILL.md b/skills/autonomous-agent-patterns/SKILL.md new file mode 100644 index 00000000..ff5b79c3 --- /dev/null +++ b/skills/autonomous-agent-patterns/SKILL.md @@ -0,0 +1,761 @@ +--- +name: autonomous-agent-patterns +description: "Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use when building AI agents, designing tool APIs, implementing permission systems, or creating autonomous coding assistants." +--- + +# 🕹️ Autonomous Agent Patterns + +> Design patterns for building autonomous coding agents, inspired by [Cline](https://github.com/cline/cline) and [OpenAI Codex](https://github.com/openai/codex). + +## When to Use This Skill + +Use this skill when: + +- Building autonomous AI agents +- Designing tool/function calling APIs +- Implementing permission and approval systems +- Creating browser automation for agents +- Designing human-in-the-loop workflows + +--- + +## 1. Core Agent Architecture + +### 1.1 Agent Loop + +``` +┌─────────────────────────────────────────────────────────────┐ +│ AGENT LOOP │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Think │───▶│ Decide │───▶│ Act │ │ +│ │ (Reason) │ │ (Plan) │ │ (Execute)│ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ ▲ │ │ +│ │ ┌──────────┐ │ │ +│ └─────────│ Observe │◀─────────┘ │ +│ │ (Result) │ │ +│ └──────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +```python +class AgentLoop: + def __init__(self, llm, tools, max_iterations=50): + self.llm = llm + self.tools = {t.name: t for t in tools} + self.max_iterations = max_iterations + self.history = [] + + def run(self, task: str) -> str: + self.history.append({"role": "user", "content": task}) + + for i in range(self.max_iterations): + # Think: Get LLM response with tool options + response = self.llm.chat( + messages=self.history, + tools=self._format_tools(), + tool_choice="auto" + ) + + # Decide: Check if agent wants to use a tool + if response.tool_calls: + for tool_call in response.tool_calls: + # Act: Execute the tool + result = self._execute_tool(tool_call) + + # Observe: Add result to history + self.history.append({ + "role": "tool", + "tool_call_id": tool_call.id, + "content": str(result) + }) + else: + # No more tool calls = task complete + return response.content + + return "Max iterations reached" + + def _execute_tool(self, tool_call) -> Any: + tool = self.tools[tool_call.name] + args = json.loads(tool_call.arguments) + return tool.execute(**args) +``` + +### 1.2 Multi-Model Architecture + +```python +class MultiModelAgent: + """ + Use different models for different purposes: + - Fast model for planning + - Powerful model for complex reasoning + - Specialized model for code generation + """ + + def __init__(self): + self.models = { + "fast": "gpt-3.5-turbo", # Quick decisions + "smart": "gpt-4-turbo", # Complex reasoning + "code": "claude-3-sonnet", # Code generation + } + + def select_model(self, task_type: str) -> str: + if task_type == "planning": + return self.models["fast"] + elif task_type == "analysis": + return self.models["smart"] + elif task_type == "code": + return self.models["code"] + return self.models["smart"] +``` + +--- + +## 2. Tool Design Patterns + +### 2.1 Tool Schema + +```python +class Tool: + """Base class for agent tools""" + + @property + def schema(self) -> dict: + """JSON Schema for the tool""" + return { + "name": self.name, + "description": self.description, + "parameters": { + "type": "object", + "properties": self._get_parameters(), + "required": self._get_required() + } + } + + def execute(self, **kwargs) -> ToolResult: + """Execute the tool and return result""" + raise NotImplementedError + +class ReadFileTool(Tool): + name = "read_file" + description = "Read the contents of a file from the filesystem" + + def _get_parameters(self): + return { + "path": { + "type": "string", + "description": "Absolute path to the file" + }, + "start_line": { + "type": "integer", + "description": "Line to start reading from (1-indexed)" + }, + "end_line": { + "type": "integer", + "description": "Line to stop reading at (inclusive)" + } + } + + def _get_required(self): + return ["path"] + + def execute(self, path: str, start_line: int = None, end_line: int = None) -> ToolResult: + try: + with open(path, 'r') as f: + lines = f.readlines() + + if start_line and end_line: + lines = lines[start_line-1:end_line] + + return ToolResult( + success=True, + output="".join(lines) + ) + except FileNotFoundError: + return ToolResult( + success=False, + error=f"File not found: {path}" + ) +``` + +### 2.2 Essential Agent Tools + +```python +CODING_AGENT_TOOLS = { + # File operations + "read_file": "Read file contents", + "write_file": "Create or overwrite a file", + "edit_file": "Make targeted edits to a file", + "list_directory": "List files and folders", + "search_files": "Search for files by pattern", + + # Code understanding + "search_code": "Search for code patterns (grep)", + "get_definition": "Find function/class definition", + "get_references": "Find all references to a symbol", + + # Terminal + "run_command": "Execute a shell command", + "read_output": "Read command output", + "send_input": "Send input to running command", + + # Browser (optional) + "open_browser": "Open URL in browser", + "click_element": "Click on page element", + "type_text": "Type text into input", + "screenshot": "Capture screenshot", + + # Context + "ask_user": "Ask the user a question", + "search_web": "Search the web for information" +} +``` + +### 2.3 Edit Tool Design + +```python +class EditFileTool(Tool): + """ + Precise file editing with conflict detection. + Uses search/replace pattern for reliable edits. + """ + + name = "edit_file" + description = "Edit a file by replacing specific content" + + def execute( + self, + path: str, + search: str, + replace: str, + expected_occurrences: int = 1 + ) -> ToolResult: + """ + Args: + path: File to edit + search: Exact text to find (must match exactly, including whitespace) + replace: Text to replace with + expected_occurrences: How many times search should appear (validation) + """ + with open(path, 'r') as f: + content = f.read() + + # Validate + actual_occurrences = content.count(search) + if actual_occurrences != expected_occurrences: + return ToolResult( + success=False, + error=f"Expected {expected_occurrences} occurrences, found {actual_occurrences}" + ) + + if actual_occurrences == 0: + return ToolResult( + success=False, + error="Search text not found in file" + ) + + # Apply edit + new_content = content.replace(search, replace) + + with open(path, 'w') as f: + f.write(new_content) + + return ToolResult( + success=True, + output=f"Replaced {actual_occurrences} occurrence(s)" + ) +``` + +--- + +## 3. Permission & Safety Patterns + +### 3.1 Permission Levels + +```python +class PermissionLevel(Enum): + # Fully automatic - no user approval needed + AUTO = "auto" + + # Ask once per session + ASK_ONCE = "ask_once" + + # Ask every time + ASK_EACH = "ask_each" + + # Never allow + NEVER = "never" + +PERMISSION_CONFIG = { + # Low risk - can auto-approve + "read_file": PermissionLevel.AUTO, + "list_directory": PermissionLevel.AUTO, + "search_code": PermissionLevel.AUTO, + + # Medium risk - ask once + "write_file": PermissionLevel.ASK_ONCE, + "edit_file": PermissionLevel.ASK_ONCE, + + # High risk - ask each time + "run_command": PermissionLevel.ASK_EACH, + "delete_file": PermissionLevel.ASK_EACH, + + # Dangerous - never auto-approve + "sudo_command": PermissionLevel.NEVER, + "format_disk": PermissionLevel.NEVER +} +``` + +### 3.2 Approval UI Pattern + +```python +class ApprovalManager: + def __init__(self, ui, config): + self.ui = ui + self.config = config + self.session_approvals = {} + + def request_approval(self, tool_name: str, args: dict) -> bool: + level = self.config.get(tool_name, PermissionLevel.ASK_EACH) + + if level == PermissionLevel.AUTO: + return True + + if level == PermissionLevel.NEVER: + self.ui.show_error(f"Tool '{tool_name}' is not allowed") + return False + + if level == PermissionLevel.ASK_ONCE: + if tool_name in self.session_approvals: + return self.session_approvals[tool_name] + + # Show approval dialog + approved = self.ui.show_approval_dialog( + tool=tool_name, + args=args, + risk_level=self._assess_risk(tool_name, args) + ) + + if level == PermissionLevel.ASK_ONCE: + self.session_approvals[tool_name] = approved + + return approved + + def _assess_risk(self, tool_name: str, args: dict) -> str: + """Analyze specific call for risk level""" + if tool_name == "run_command": + cmd = args.get("command", "") + if any(danger in cmd for danger in ["rm -rf", "sudo", "chmod"]): + return "HIGH" + return "MEDIUM" +``` + +### 3.3 Sandboxing + +```python +class SandboxedExecution: + """ + Execute code/commands in isolated environment + """ + + def __init__(self, workspace_dir: str): + self.workspace = workspace_dir + self.allowed_commands = ["npm", "python", "node", "git", "ls", "cat"] + self.blocked_paths = ["/etc", "/usr", "/bin", os.path.expanduser("~")] + + def validate_path(self, path: str) -> bool: + """Ensure path is within workspace""" + real_path = os.path.realpath(path) + workspace_real = os.path.realpath(self.workspace) + return real_path.startswith(workspace_real) + + def validate_command(self, command: str) -> bool: + """Check if command is allowed""" + cmd_parts = shlex.split(command) + if not cmd_parts: + return False + + base_cmd = cmd_parts[0] + return base_cmd in self.allowed_commands + + def execute_sandboxed(self, command: str) -> ToolResult: + if not self.validate_command(command): + return ToolResult( + success=False, + error=f"Command not allowed: {command}" + ) + + # Execute in isolated environment + result = subprocess.run( + command, + shell=True, + cwd=self.workspace, + capture_output=True, + timeout=30, + env={ + **os.environ, + "HOME": self.workspace, # Isolate home directory + } + ) + + return ToolResult( + success=result.returncode == 0, + output=result.stdout.decode(), + error=result.stderr.decode() if result.returncode != 0 else None + ) +``` + +--- + +## 4. Browser Automation + +### 4.1 Browser Tool Pattern + +```python +class BrowserTool: + """ + Browser automation for agents using Playwright/Puppeteer. + Enables visual debugging and web testing. + """ + + def __init__(self, headless: bool = True): + self.browser = None + self.page = None + self.headless = headless + + async def open_url(self, url: str) -> ToolResult: + """Navigate to URL and return page info""" + if not self.browser: + self.browser = await playwright.chromium.launch(headless=self.headless) + self.page = await self.browser.new_page() + + await self.page.goto(url) + + # Capture state + screenshot = await self.page.screenshot(type='png') + title = await self.page.title() + + return ToolResult( + success=True, + output=f"Loaded: {title}", + metadata={ + "screenshot": base64.b64encode(screenshot).decode(), + "url": self.page.url + } + ) + + async def click(self, selector: str) -> ToolResult: + """Click on an element""" + try: + await self.page.click(selector, timeout=5000) + await self.page.wait_for_load_state("networkidle") + + screenshot = await self.page.screenshot() + return ToolResult( + success=True, + output=f"Clicked: {selector}", + metadata={"screenshot": base64.b64encode(screenshot).decode()} + ) + except TimeoutError: + return ToolResult( + success=False, + error=f"Element not found: {selector}" + ) + + async def type_text(self, selector: str, text: str) -> ToolResult: + """Type text into an input""" + await self.page.fill(selector, text) + return ToolResult(success=True, output=f"Typed into {selector}") + + async def get_page_content(self) -> ToolResult: + """Get accessible text content of the page""" + content = await self.page.evaluate(""" + () => { + // Get visible text + const walker = document.createTreeWalker( + document.body, + NodeFilter.SHOW_TEXT, + null, + false + ); + + let text = ''; + while (walker.nextNode()) { + const node = walker.currentNode; + if (node.textContent.trim()) { + text += node.textContent.trim() + '\\n'; + } + } + return text; + } + """) + return ToolResult(success=True, output=content) +``` + +### 4.2 Visual Agent Pattern + +```python +class VisualAgent: + """ + Agent that uses screenshots to understand web pages. + Can identify elements visually without selectors. + """ + + def __init__(self, llm, browser): + self.llm = llm + self.browser = browser + + async def describe_page(self) -> str: + """Use vision model to describe current page""" + screenshot = await self.browser.screenshot() + + response = self.llm.chat([ + { + "role": "user", + "content": [ + {"type": "text", "text": "Describe this webpage. List all interactive elements you see."}, + {"type": "image", "data": screenshot} + ] + } + ]) + + return response.content + + async def find_and_click(self, description: str) -> ToolResult: + """Find element by visual description and click it""" + screenshot = await self.browser.screenshot() + + # Ask vision model to find element + response = self.llm.chat([ + { + "role": "user", + "content": [ + { + "type": "text", + "text": f""" + Find the element matching: "{description}" + Return the approximate coordinates as JSON: {{"x": number, "y": number}} + """ + }, + {"type": "image", "data": screenshot} + ] + } + ]) + + coords = json.loads(response.content) + await self.browser.page.mouse.click(coords["x"], coords["y"]) + + return ToolResult(success=True, output=f"Clicked at ({coords['x']}, {coords['y']})") +``` + +--- + +## 5. Context Management + +### 5.1 Context Injection Patterns + +````python +class ContextManager: + """ + Manage context provided to the agent. + Inspired by Cline's @-mention patterns. + """ + + def __init__(self, workspace: str): + self.workspace = workspace + self.context = [] + + def add_file(self, path: str) -> None: + """@file - Add file contents to context""" + with open(path, 'r') as f: + content = f.read() + + self.context.append({ + "type": "file", + "path": path, + "content": content + }) + + def add_folder(self, path: str, max_files: int = 20) -> None: + """@folder - Add all files in folder""" + for root, dirs, files in os.walk(path): + for file in files[:max_files]: + file_path = os.path.join(root, file) + self.add_file(file_path) + + def add_url(self, url: str) -> None: + """@url - Fetch and add URL content""" + response = requests.get(url) + content = html_to_markdown(response.text) + + self.context.append({ + "type": "url", + "url": url, + "content": content + }) + + def add_problems(self, diagnostics: list) -> None: + """@problems - Add IDE diagnostics""" + self.context.append({ + "type": "diagnostics", + "problems": diagnostics + }) + + def format_for_prompt(self) -> str: + """Format all context for LLM prompt""" + parts = [] + for item in self.context: + if item["type"] == "file": + parts.append(f"## File: {item['path']}\n```\n{item['content']}\n```") + elif item["type"] == "url": + parts.append(f"## URL: {item['url']}\n{item['content']}") + elif item["type"] == "diagnostics": + parts.append(f"## Problems:\n{json.dumps(item['problems'], indent=2)}") + + return "\n\n".join(parts) +```` + +### 5.2 Checkpoint/Resume + +```python +class CheckpointManager: + """ + Save and restore agent state for long-running tasks. + """ + + def __init__(self, storage_dir: str): + self.storage_dir = storage_dir + os.makedirs(storage_dir, exist_ok=True) + + def save_checkpoint(self, session_id: str, state: dict) -> str: + """Save current agent state""" + checkpoint = { + "timestamp": datetime.now().isoformat(), + "session_id": session_id, + "history": state["history"], + "context": state["context"], + "workspace_state": self._capture_workspace(state["workspace"]), + "metadata": state.get("metadata", {}) + } + + path = os.path.join(self.storage_dir, f"{session_id}.json") + with open(path, 'w') as f: + json.dump(checkpoint, f, indent=2) + + return path + + def restore_checkpoint(self, checkpoint_path: str) -> dict: + """Restore agent state from checkpoint""" + with open(checkpoint_path, 'r') as f: + checkpoint = json.load(f) + + return { + "history": checkpoint["history"], + "context": checkpoint["context"], + "workspace": self._restore_workspace(checkpoint["workspace_state"]), + "metadata": checkpoint["metadata"] + } + + def _capture_workspace(self, workspace: str) -> dict: + """Capture relevant workspace state""" + # Git status, file hashes, etc. + return { + "git_ref": subprocess.getoutput(f"cd {workspace} && git rev-parse HEAD"), + "git_dirty": subprocess.getoutput(f"cd {workspace} && git status --porcelain") + } +``` + +--- + +## 6. MCP (Model Context Protocol) Integration + +### 6.1 MCP Server Pattern + +```python +from mcp import Server, Tool + +class MCPAgent: + """ + Agent that can dynamically discover and use MCP tools. + 'Add a tool that...' pattern from Cline. + """ + + def __init__(self, llm): + self.llm = llm + self.mcp_servers = {} + self.available_tools = {} + + def connect_server(self, name: str, config: dict) -> None: + """Connect to an MCP server""" + server = Server(config) + self.mcp_servers[name] = server + + # Discover tools + tools = server.list_tools() + for tool in tools: + self.available_tools[tool.name] = { + "server": name, + "schema": tool.schema + } + + async def create_tool(self, description: str) -> str: + """ + Create a new MCP server based on user description. + 'Add a tool that fetches Jira tickets' + """ + # Generate MCP server code + code = self.llm.generate(f""" + Create a Python MCP server with a tool that does: + {description} + + Use the FastMCP framework. Include proper error handling. + Return only the Python code. + """) + + # Save and install + server_name = self._extract_name(description) + path = f"./mcp_servers/{server_name}/server.py" + + with open(path, 'w') as f: + f.write(code) + + # Hot-reload + self.connect_server(server_name, {"path": path}) + + return f"Created tool: {server_name}" +``` + +--- + +## Best Practices Checklist + +### Agent Design + +- [ ] Clear task decomposition +- [ ] Appropriate tool granularity +- [ ] Error handling at each step +- [ ] Progress visibility to user + +### Safety + +- [ ] Permission system implemented +- [ ] Dangerous operations blocked +- [ ] Sandbox for untrusted code +- [ ] Audit logging enabled + +### UX + +- [ ] Approval UI is clear +- [ ] Progress updates provided +- [ ] Undo/rollback available +- [ ] Explanation of actions + +--- + +## Resources + +- [Cline](https://github.com/cline/cline) +- [OpenAI Codex](https://github.com/openai/codex) +- [Model Context Protocol](https://modelcontextprotocol.io/) +- [Anthropic Tool Use](https://docs.anthropic.com/claude/docs/tool-use) diff --git a/skills/bun-development/SKILL.md b/skills/bun-development/SKILL.md new file mode 100644 index 00000000..4dfb8adf --- /dev/null +++ b/skills/bun-development/SKILL.md @@ -0,0 +1,691 @@ +--- +name: bun-development +description: "Modern JavaScript/TypeScript development with Bun runtime. Covers package management, bundling, testing, and migration from Node.js. Use when working with Bun, optimizing JS/TS development speed, or migrating from Node.js to Bun." +--- + +# ⚡ Bun Development + +> Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by [oven-sh/bun](https://github.com/oven-sh/bun). + +## When to Use This Skill + +Use this skill when: + +- Starting new JS/TS projects with Bun +- Migrating from Node.js to Bun +- Optimizing development speed +- Using Bun's built-in tools (bundler, test runner) +- Troubleshooting Bun-specific issues + +--- + +## 1. Getting Started + +### 1.1 Installation + +```bash +# macOS / Linux +curl -fsSL https://bun.sh/install | bash + +# Windows +powershell -c "irm bun.sh/install.ps1 | iex" + +# Homebrew +brew tap oven-sh/bun +brew install bun + +# npm (if needed) +npm install -g bun + +# Upgrade +bun upgrade +``` + +### 1.2 Why Bun? + +| Feature | Bun | Node.js | +| :-------------- | :------------- | :-------------------------- | +| Startup time | ~25ms | ~100ms+ | +| Package install | 10-100x faster | Baseline | +| TypeScript | Native | Requires transpiler | +| JSX | Native | Requires transpiler | +| Test runner | Built-in | External (Jest, Vitest) | +| Bundler | Built-in | External (Webpack, esbuild) | + +--- + +## 2. Project Setup + +### 2.1 Create New Project + +```bash +# Initialize project +bun init + +# Creates: +# ├── package.json +# ├── tsconfig.json +# ├── index.ts +# └── README.md + +# With specific template +bun create