@musashishao/agent-kit 1.8.1 → 1.9.0

package/.agent/skills/autonomous-agent-patterns/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: autonomous-agent-patterns
+description: "Design patterns for building autonomous coding agents. Covers agent loops, tool design, permission systems, sandboxing, and context management. Inspired by Cline, OpenAI Codex, and production agent systems."
+version: "1.0.0"
+source: "antigravity-awesome-skills (adapted)"
+---
+
+# 🕹️ 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
+
+- Building coding assistants or autonomous agents
+- Designing tool interfaces for AI
+- Implementing permission/approval systems
+- Creating sandboxed execution environments
+- Managing agent context and memory
+
+---
+
+## 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"
+```
+
+### 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-4o-mini",       # Quick decisions
+            "smart": "gpt-4o",            # Complex reasoning
+            "code": "claude-3-5-sonnet",  # Code generation
+        }
+    
+    def select_model(self, task_type: str) -> str:
+        model_map = {
+            "planning": "fast",
+            "analysis": "smart",
+            "code": "code"
+        }
+        return self.models.get(model_map.get(task_type, "smart"))
+```
+
+---
+
+## 2. Tool Design Patterns
+
+### 2.1 Tool Schema
+
+```python
+@dataclass
+class ToolDefinition:
+    name: str
+    description: str
+    parameters: dict
+    
+    # Metadata for permission system
+    risk_level: str = "low"  # low, medium, high
+    requires_approval: bool = False
+    timeout_seconds: int = 30
+
+ESSENTIAL_TOOLS = [
+    ToolDefinition(
+        name="read_file",
+        description="Read contents of a file",
+        parameters={"path": {"type": "string", "required": True}},
+        risk_level="low"
+    ),
+    ToolDefinition(
+        name="write_file",
+        description="Write content to a file",
+        parameters={
+            "path": {"type": "string", "required": True},
+            "content": {"type": "string", "required": True}
+        },
+        risk_level="medium",
+        requires_approval=True
+    ),
+    ToolDefinition(
+        name="run_command",
+        description="Execute a shell command",
+        parameters={"command": {"type": "string", "required": True}},
+        risk_level="high",
+        requires_approval=True,
+        timeout_seconds=60
+    )
+]
+```
+
+### 2.2 Edit Tool Design
+
+```python
+class EditTool:
+    """
+    Specialized tool for making targeted file edits.
+    Better than full file replace for large files.
+    """
+    
+    def apply_edit(
+        self,
+        file_path: str,
+        target_content: str,    # Content to find
+        replacement: str,       # Content to replace with
+        start_line: int = None, # Optional line hints
+        end_line: int = None
+    ) -> ToolResult:
+        content = self._read_file(file_path)
+        
+        # Find target content
+        if target_content not in content:
+            # Try fuzzy matching
+            match = self._fuzzy_find(content, target_content)
+            if not match:
+                return ToolResult(
+                    success=False,
+                    error="Target content not found"
+                )
+            target_content = match
+        
+        # Apply replacement
+        new_content = content.replace(target_content, replacement, 1)
+        
+        # Validate (syntax check for code files)
+        if not self._validate(file_path, new_content):
+            return ToolResult(
+                success=False,
+                error="Edit would cause syntax error"
+            )
+        
+        self._write_file(file_path, new_content)
+        return ToolResult(success=True)
+```
+
+---
+
+## 3. Permission & Safety Patterns
+
+### 3.1 Permission Levels
+
+```python
+class PermissionLevel(Enum):
+    AUTO = "auto"           # Fully automatic
+    ASK_ONCE = "ask_once"   # Ask once per session
+    ASK_EACH = "ask_each"   # Ask every time
+    NEVER = "never"         # Never allow
+
+PERMISSION_CONFIG = {
+    # Low risk - 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 Manager
+
+```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
+```
+
+### 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
+        return cmd_parts[0] in self.allowed_commands
+    
+    def execute_sandboxed(self, command: str) -> ToolResult:
+        if not self.validate_command(command):
+            return ToolResult(success=False, error="Command not allowed")
+        
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=self.workspace,
+            capture_output=True,
+            timeout=30,
+            env={**os.environ, "HOME": self.workspace}
+        )
+        
+        return ToolResult(
+            success=result.returncode == 0,
+            output=result.stdout.decode(),
+            error=result.stderr.decode() if result.returncode != 0 else None
+        )
+```
+
+---
+
+## 4. Context Management
+
+### 4.1 Context Injection Patterns
+
+```python
+class ContextManager:
+    """Manage what context the agent sees"""
+    
+    def __init__(self, max_tokens: int = 100000):
+        self.max_tokens = max_tokens
+        self.priority_order = [
+            "system_prompt",
+            "user_request",
+            "recent_tool_results",
+            "relevant_files",
+            "conversation_history"
+        ]
+    
+    def build_context(self, components: dict) -> list:
+        """Build context within token budget"""
+        context = []
+        remaining_tokens = self.max_tokens
+        
+        for priority in self.priority_order:
+            if priority not in components:
+                continue
+            
+            content = components[priority]
+            tokens = self._count_tokens(content)
+            
+            if tokens <= remaining_tokens:
+                context.append(content)
+                remaining_tokens -= tokens
+            else:
+                # Truncate or summarize
+                truncated = self._truncate(content, remaining_tokens)
+                context.append(truncated)
+                break
+        
+        return context
+```
+
+### 4.2 Checkpoint/Resume
+
+```python
+class AgentCheckpoint:
+    """Save and restore agent state"""
+    
+    def save(self, agent_state: dict, checkpoint_id: str):
+        checkpoint = {
+            "id": checkpoint_id,
+            "timestamp": datetime.now().isoformat(),
+            "messages": agent_state["messages"],
+            "tool_results": agent_state["tool_results"],
+            "files_modified": agent_state["files_modified"],
+            "current_task": agent_state["current_task"]
+        }
+        
+        with open(f".agent/checkpoints/{checkpoint_id}.json", "w") as f:
+            json.dump(checkpoint, f)
+    
+    def restore(self, checkpoint_id: str) -> dict:
+        with open(f".agent/checkpoints/{checkpoint_id}.json") as f:
+            return json.load(f)
+    
+    def list_checkpoints(self) -> list:
+        path = Path(".agent/checkpoints")
+        return sorted(path.glob("*.json"), key=lambda p: p.stat().st_mtime)
+```
+
+---
+
+## 5. Best Practices Checklist
+
+### Agent Design
+- ✅ Clear separation: Think → Decide → Act → Observe
+- ✅ Max iteration limits to prevent infinite loops
+- ✅ Multi-model routing for cost/performance
+- ✅ Graceful degradation on errors
+
+### Safety
+- ✅ Permission levels for all tools
+- ✅ Sandboxed command execution
+- ✅ Path validation (no escape from workspace)
+- ✅ Dangerous command blocklist
+
+### UX
+- ✅ Show what agent is thinking
+- ✅ Clear approval dialogs with risk indicators
+- ✅ Ability to cancel/interrupt
+- ✅ Checkpoint/resume for long tasks
+
+---
+
+## Related Skills
+
+- `langgraph` - Graph-based agent architecture
+- `crewai` - Multi-agent collaboration
+- `mcp-builder` - MCP server patterns
+- `agent-memory-systems` - Memory architectures
+- `verification-gate` - Verify before claiming done

package/.agent/skills/aws-penetration-testing/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: aws-penetration-testing
+description: "Specialized skill for auditing AWS environments. Covers IAM misconfigurations, S3 bucket leaks, CloudTrail evasion, and Lambda exploitation."
+version: "1.0.0"
+---
+
+# ☁️ AWS Penetration Testing
+
+You are a Cloud Security auditor. You know that AWS security is 90% IAM and 10% everything else. You focus on finding paths to Privilege Escalation and data exfiltration.
+
+---
+
+## Key Attack Areas
+
+### 1. IAM Misconfigurations
+Finding users or roles with "Over-privileged" permissions.
+- **High Risk**: `iam:PutUserPolicy`, `iam:CreateAccessKey`, `sts:AssumeRole`.
+- **Tool**: `Pacu` (AWS exploitation framework).
+
+### 2. S3 Bucket Leaks
+Publicly accessible buckets containing sensitive data.
+- **Discovery**: `cloud_enum`, `s3scanner`.
+- **Command**: `aws s3 ls s3://target-bucket --no-sign-request`.
+
+### 3. Metadata Service (IMDS) Attacks
+Stealing temporary credentials from an EC2 instance.
+- **Exploit**: SSRF on a web app running on EC2 -> Query `http://169.254.169.254/latest/meta-data/iam/security-credentials/`.
+
+---
+
+## Privilege Escalation Patterns
+
+1. **Policy Attachment**: If you have `iam:AttachUserPolicy`, attach `AdministratorAccess` to yourself.
+2. **Access Key Creation**: If you have `iam:CreateAccessKey` for another user, create a key and login as them.
+3. **Lambda Trigger**: Update a Lambda function's code to send you a reverse shell when it's triggered.
+
+---
+
+## Persistence in AWS
+- Create a secondary Access Key for a "quiet" user.
+- Add an external account to a high-privilege Role's Trust Policy.
+- Set up a scheduled Lambda function that pings your C2.
+
+---
+
+## Related Skills
+
+- `aws-serverless` - Understanding the architecture
+- `cloud-penetration-testing` - General cloud security
+- `vulnerability-scanner` - Recon tools