opencode-skills-collection 4.0.52 → 4.0.54

package/bundled-skills/langgraph/references/detailed-guide.md

@@ -0,0 +1,455 @@
+# LangGraph - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Capabilities
+
+- Graph construction (StateGraph)
+- State management and reducers
+- Node and edge definitions
+- Conditional routing
+- Checkpointers and persistence
+- Human-in-the-loop patterns
+- Tool integration
+- Streaming and async execution
+
+
+## Scope
+
+- 0: Python-only (TypeScript in early stages)
+- 1: Learning curve for graph concepts
+- 2: State management complexity
+- 3: Debugging can be challenging
+
+
+## Ecosystem
+
+### Primary
+
+- LangGraph
+- LangChain
+- LangSmith (observability)
+
+### Common_integrations
+
+- OpenAI / Anthropic / Google
+- Tavily (search)
+- SQLite / PostgreSQL (persistence)
+- Redis (state store)
+
+### Platforms
+
+- Python applications
+- FastAPI / Flask backends
+- Cloud deployments
+
+
+## Patterns
+
+### Basic Agent Graph
+
+Simple ReAct-style agent with tools
+
+**When to use**: Single agent with tool calling
+
+from typing import Annotated, TypedDict
+from langgraph.graph import StateGraph, START, END
+from langgraph.graph.message import add_messages
+from langgraph.prebuilt import ToolNode
+from langchain_openai import ChatOpenAI
+from langchain_core.tools import tool
+
+# 1. Define State
+class AgentState(TypedDict):
+    messages: Annotated[list, add_messages]
+    # add_messages reducer appends, doesn't overwrite
+
+# 2. Define Tools
+@tool
+def search(query: str) -> str:
+    """Search the web for information."""
+    # Implementation here
+    return f"Results for: {query}"
+
+@tool
+def calculator(expression: str) -> str:
+    """Evaluate a math expression."""
+    return str(safe_math_evaluator(expression))
+
+tools = [search, calculator]
+
+# 3. Create LLM with tools
+llm = ChatOpenAI(model="gpt-4o").bind_tools(tools)
+
+# 4. Define Nodes
+def agent(state: AgentState) -> dict:
+    """The agent node - calls LLM."""
+    response = llm.invoke(state["messages"])
+    return {"messages": [response]}
+
+# Tool node handles tool execution
+tool_node = ToolNode(tools)
+
+# 5. Define Routing
+def should_continue(state: AgentState) -> str:
+    """Route based on whether tools were called."""
+    last_message = state["messages"][-1]
+    if last_message.tool_calls:
+        return "tools"
+    return END
+
+# 6. Build Graph
+graph = StateGraph(AgentState)
+
+# Add nodes
+graph.add_node("agent", agent)
+graph.add_node("tools", tool_node)
+
+# Add edges
+graph.add_edge(START, "agent")
+graph.add_conditional_edges("agent", should_continue, ["tools", END])
+graph.add_edge("tools", "agent")  # Loop back
+
+# Compile
+app = graph.compile()
+
+# 7. Run
+result = app.invoke({
+    "messages": [("user", "What is 25 * 4?")]
+})
+
+### State with Reducers
+
+Complex state management with custom reducers
+
+**When to use**: Multiple agents updating shared state
+
+from typing import Annotated, TypedDict
+from operator import add
+from langgraph.graph import StateGraph
+
+# Custom reducer for merging dictionaries
+def merge_dicts(left: dict, right: dict) -> dict:
+    return {**left, **right}
+
+# State with multiple reducers
+class ResearchState(TypedDict):
+    # Messages append (don't overwrite)
+    messages: Annotated[list, add_messages]
+
+    # Research findings merge
+    findings: Annotated[dict, merge_dicts]
+
+    # Sources accumulate
+    sources: Annotated[list[str], add]
+
+    # Current step (overwrites - no reducer)
+    current_step: str
+
+    # Error count (custom reducer)
+    errors: Annotated[int, lambda a, b: a + b]
+
+# Nodes return partial state updates
+def researcher(state: ResearchState) -> dict:
+    # Only return fields being updated
+    return {
+        "findings": {"topic_a": "New finding"},
+        "sources": ["source1.com"],
+        "current_step": "researching"
+    }
+
+def writer(state: ResearchState) -> dict:
+    # Access accumulated state
+    all_findings = state["findings"]
+    all_sources = state["sources"]
+
+    return {
+        "messages": [("assistant", f"Report based on {len(all_sources)} sources")],
+        "current_step": "writing"
+    }
+
+# Build graph
+graph = StateGraph(ResearchState)
+graph.add_node("researcher", researcher)
+graph.add_node("writer", writer)
+# ... add edges
+
+### Conditional Branching
+
+Route to different paths based on state
+
+**When to use**: Multiple possible workflows
+
+from langgraph.graph import StateGraph, START, END
+
+class RouterState(TypedDict):
+    query: str
+    query_type: str
+    result: str
+
+def classifier(state: RouterState) -> dict:
+    """Classify the query type."""
+    query = state["query"].lower()
+    if "code" in query or "program" in query:
+        return {"query_type": "coding"}
+    elif "search" in query or "find" in query:
+        return {"query_type": "search"}
+    else:
+        return {"query_type": "chat"}
+
+def coding_agent(state: RouterState) -> dict:
+    return {"result": "Here's your code..."}
+
+def search_agent(state: RouterState) -> dict:
+    return {"result": "Search results..."}
+
+def chat_agent(state: RouterState) -> dict:
+    return {"result": "Let me help..."}
+
+# Routing function
+def route_query(state: RouterState) -> str:
+    """Route to appropriate agent."""
+    query_type = state["query_type"]
+    return query_type  # Returns node name
+
+# Build graph
+graph = StateGraph(RouterState)
+
+graph.add_node("classifier", classifier)
+graph.add_node("coding", coding_agent)
+graph.add_node("search", search_agent)
+graph.add_node("chat", chat_agent)
+
+graph.add_edge(START, "classifier")
+
+# Conditional edges from classifier
+graph.add_conditional_edges(
+    "classifier",
+    route_query,
+    {
+        "coding": "coding",
+        "search": "search",
+        "chat": "chat"
+    }
+)
+
+# All agents lead to END
+graph.add_edge("coding", END)
+graph.add_edge("search", END)
+graph.add_edge("chat", END)
+
+app = graph.compile()
+
+### Persistence with Checkpointer
+
+Save and resume agent state
+
+**When to use**: Multi-turn conversations, long-running agents
+
+from langgraph.graph import StateGraph
+from langgraph.checkpoint.sqlite import SqliteSaver
+from langgraph.checkpoint.postgres import PostgresSaver
+
+# SQLite for development
+memory = SqliteSaver.from_conn_string(":memory:")
+# Or persistent file
+memory = SqliteSaver.from_conn_string("agent_state.db")
+
+# PostgreSQL for production
+# memory = PostgresSaver.from_conn_string(DATABASE_URL)
+
+# Compile with checkpointer
+app = graph.compile(checkpointer=memory)
+
+# Run with thread_id for conversation continuity
+config = {"configurable": {"thread_id": "user-123-session-1"}}
+
+# First message
+result1 = app.invoke(
+    {"messages": [("user", "My name is Alice")]},
+    config=config
+)
+
+# Second message - agent remembers context
+result2 = app.invoke(
+    {"messages": [("user", "What's my name?")]},
+    config=config
+)
+# Agent knows name is Alice!
+
+# Get conversation history
+state = app.get_state(config)
+print(state.values["messages"])
+
+# List all checkpoints
+for checkpoint in app.get_state_history(config):
+    print(checkpoint.config, checkpoint.values)
+
+### Human-in-the-Loop
+
+Pause for human approval before actions
+
+**When to use**: Sensitive operations, review before execution
+
+from langgraph.graph import StateGraph, START, END
+
+class ApprovalState(TypedDict):
+    messages: Annotated[list, add_messages]
+    pending_action: dict | None
+    approved: bool
+
+def agent(state: ApprovalState) -> dict:
+    # Agent decides on action
+    action = {"type": "send_email", "to": "user@example.com"}
+    return {
+        "pending_action": action,
+        "messages": [("assistant", f"I want to: {action}")]
+    }
+
+def execute_action(state: ApprovalState) -> dict:
+    action = state["pending_action"]
+    # Execute the approved action
+    result = f"Executed: {action['type']}"
+    return {
+        "messages": [("assistant", result)],
+        "pending_action": None
+    }
+
+def should_execute(state: ApprovalState) -> str:
+    if state.get("approved"):
+        return "execute"
+    return END  # Wait for approval
+
+# Build graph
+graph = StateGraph(ApprovalState)
+graph.add_node("agent", agent)
+graph.add_node("execute", execute_action)
+
+graph.add_edge(START, "agent")
+graph.add_conditional_edges("agent", should_execute, ["execute", END])
+graph.add_edge("execute", END)
+
+# Compile with interrupt_before for human review
+app = graph.compile(
+    checkpointer=memory,
+    interrupt_before=["execute"]  # Pause before execution
+)
+
+# Run until interrupt
+config = {"configurable": {"thread_id": "approval-flow"}}
+result = app.invoke({"messages": [("user", "Send report")]}, config)
+
+# Agent paused - get pending state
+state = app.get_state(config)
+pending = state.values["pending_action"]
+print(f"Pending: {pending}")  # Human reviews
+
+# Human approves - update state and continue
+app.update_state(config, {"approved": True})
+result = app.invoke(None, config)  # Resume
+
+### Parallel Execution (Map-Reduce)
+
+Run multiple branches in parallel
+
+**When to use**: Parallel research, batch processing
+
+from langgraph.graph import StateGraph, START, END, Send
+from langgraph.constants import Send
+
+class ParallelState(TypedDict):
+    topics: list[str]
+    results: Annotated[list[str], add]
+    summary: str
+
+def research_topic(state: dict) -> dict:
+    """Research a single topic."""
+    topic = state["topic"]
+    result = f"Research on {topic}..."
+    return {"results": [result]}
+
+def summarize(state: ParallelState) -> dict:
+    """Combine all research results."""
+    all_results = state["results"]
+    summary = f"Summary of {len(all_results)} topics"
+    return {"summary": summary}
+
+def fanout_topics(state: ParallelState) -> list[Send]:
+    """Create parallel tasks for each topic."""
+    return [
+        Send("research", {"topic": topic})
+        for topic in state["topics"]
+    ]
+
+# Build graph
+graph = StateGraph(ParallelState)
+graph.add_node("research", research_topic)
+graph.add_node("summarize", summarize)
+
+# Fan out to parallel research
+graph.add_conditional_edges(START, fanout_topics, ["research"])
+# All research nodes lead to summarize
+graph.add_edge("research", "summarize")
+graph.add_edge("summarize", END)
+
+app = graph.compile()
+
+result = app.invoke({
+    "topics": ["AI", "Climate", "Space"],
+    "results": []
+})
+# Research runs in parallel, then summarizes
+
+
+## Collaboration
+
+### Delegation Triggers
+
+- crewai|role-based|crew -> crewai (Need role-based multi-agent approach)
+- observability|tracing|langsmith -> langfuse (Need LLM observability)
+- structured output|json schema -> structured-output (Need structured LLM responses)
+- evaluate|benchmark|test agent -> agent-evaluation (Need to evaluate agent performance)
+
+### Production Agent Stack
+
+Skills: langgraph, langfuse, structured-output
+
+Workflow:
+
+```
+1. Design agent graph with LangGraph
+2. Add structured outputs for tool responses
+3. Integrate Langfuse for observability
+4. Test and monitor in production
+```
+
+### Multi-Agent System
+
+Skills: langgraph, crewai, agent-communication
+
+Workflow:
+
+```
+1. Design agent roles (CrewAI patterns)
+2. Implement as LangGraph with subgraphs
+3. Add inter-agent communication
+4. Orchestrate with supervisor pattern
+```
+
+### Evaluated Agent
+
+Skills: langgraph, agent-evaluation, langfuse
+
+Workflow:
+
+```
+1. Build agent with LangGraph
+2. Create evaluation suite
+3. Monitor with Langfuse
+4. Iterate based on metrics
+```
+
+
+## Related Skills
+
+Works well with: `crewai`, `autonomous-agents`, `langfuse`, `structured-output`

package/bundled-skills/laravel-development-workflow/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: laravel-development-workflow
+description: "Build and fix existing Laravel applications through root-cause diagnosis, repository-native implementation, regression coverage, and risk-based verification."
+category: development
+risk: critical
+source: community
+source_repo: Junaid-PK/laravel-development-workflow
+source_type: community
+date_added: "2026-09-02"
+author: Junaid-PK
+tags: [laravel, php, debugging, testing, development]
+tools: [claude, codex, cursor, gemini]
+license: "MIT"
+license_source: "https://github.com/Junaid-PK/laravel-development-workflow/blob/main/LICENSE"
+---
+
+# Laravel Development Workflow
+
+Make the requested Laravel behavior correct, maintainable within the existing application, and supported by evidence that matches the change's risk.
+
+## When to Use
+
+- Use when implementing a feature in an existing Laravel application.
+- Use when diagnosing and fixing a Laravel bug at its actionable root cause.
+- Use when a Laravel change needs regression coverage and proportionate verification.
+- Use when the project already has architectural or testing conventions that must be preserved.
+
+## Establish the Contract
+
+Before editing:
+
+- Read the repository instructions and inspect the relevant routes, models, controllers, actions or services, requests, policies, jobs, events, tests, and schema.
+- Trace the current behavior far enough to identify the actual change boundary and existing conventions.
+- Turn the request into a compact set of scenarios, important edge cases, and verifiable acceptance criteria. Keep this analysis in the working notes unless the user requests a separate artifact.
+- Identify authorization, validation, transaction, queue, cache, and concurrency concerns only where they can affect this behavior.
+
+Scale the analysis to the task. A focused validation fix does not need the same ceremony as a new multi-role workflow.
+
+## Fix Bugs at the Cause
+
+For a bug:
+
+1. Reproduce the failure through the narrowest reliable path.
+2. Trace the data and control flow to the actionable root cause.
+3. Add or update a regression test that fails for that cause when practical.
+4. Implement the smallest fix that restores the intended invariant.
+5. Demonstrate that the regression test passes and that nearby behavior still works.
+
+Do not substitute retries, broad exception handling, disabled validation, extra timeouts, or error suppression for a root-cause fix. If the failure cannot be reproduced locally, state what evidence is missing and use the strongest available static or targeted verification.
+
+## Build Features in the Existing Shape
+
+- Reuse the application's established patterns and naming.
+- Keep business rules in the layer where this codebase already places comparable rules.
+- Use Eloquent relationships, form requests, policies, actions, services, events, or jobs when they improve this change or match local conventions—not as mandatory ceremony.
+- Treat authorization and validation as explicit behavior at the system boundary.
+- Preserve backwards compatibility unless the request requires a breaking change.
+- Keep migrations reversible and safe for the application's supported database engines.
+
+Create factories, seeders, fixtures, or a disposable command only when realistic data is needed for development or durable test coverage. Do not leave one-off scaffolding in the product solely to exercise a small change.
+
+## Verify Proportionately
+
+Discover the project's supported commands from its configuration and documentation. Prefer this order:
+
+1. Run the narrowest affected test or reproduce the original failure.
+2. Run the relevant feature, unit, or integration test group.
+3. Run static analysis, formatting, and linting configured by the repository.
+4. Run the broader suite when the change's reach or project policy warrants it.
+
+Cover the critical observable behavior, including the happy path and whichever edge cases, validation rules, permissions, database effects, events, notifications, jobs, or API contracts are actually affected. Avoid tests that only mirror implementation details.
+
+Common commands may include:
+
+```bash
+php artisan test --filter=RelevantTest
+vendor/bin/pest --filter=RelevantTest
+vendor/bin/phpstan analyse
+vendor/bin/pint --dirty
+```
+
+Use the commands the project provides; do not install or configure tools merely because they appear in this example.
+
+## Preserve the User's Environment
+
+- Keep the change inside the requested application behavior and preserve unrelated working-tree changes.
+- Do not run destructive database operations, production commands, deployments, credential changes, or external account actions unless the user or repository instructions explicitly place them in scope.
+- Avoid exposing secrets in commands, logs, test output, or completion evidence.
+- Prefer local, reversible verification and narrowly targeted data changes.
+
+## Completion Evidence
+
+Before handing off, verify each acceptance criterion against current behavior. Report:
+
+- what changed and why it fixes or implements the requested behavior;
+- the scenarios and important edge cases covered;
+- the exact checks run and their results;
+- any check that could not run, with the concrete reason and remaining risk.
+
+Do not claim completion from code inspection alone when executable verification is available.
+
+## Limitations
+
+- This workflow requires an existing Laravel application and adapts to that repository's architecture and tooling; it does not impose a complete project structure.
+- It cannot prove production behavior when the required services, data, credentials, or environment are unavailable, so any unverified risk must be reported explicitly.
+- It does not authorize destructive database work, production changes, deployments, credential changes, or external account actions.

package/bundled-skills/laravel-expert/SKILL.md

@@ -185,6 +185,12 @@ When refactoring:
 - Do not assume cloud infrastructure
 - Keep solutions pragmatic and realistic
 
+## Example
+
+**User request:**
+
+> Build new Laravel features.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/launch-strategy/SKILL.md

@@ -349,6 +349,12 @@ If you need more context:
 ## When to Use
 This skill is applicable to execute the workflow or actions described in the overview.
 
+## Example
+
+**User request:**
+
+> Use @launch-strategy for this task: You are an expert in SaaS product launches and feature announcements.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/lead-magnets/SKILL.md

@@ -317,6 +317,12 @@ When creating a lead magnet strategy, provide:
 - **paid-ads**: For paid promotion of lead magnets
 - **social-content**: For social media promotion
 
+## Example
+
+**User request:**
+
+> Plan downloadable offers or gated resources for email capture.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/learn/SKILL.md

@@ -148,6 +148,11 @@ Before finishing, check that:
 - The next step is clear.
 - Any generated files or code are actually usable in the target environment.
 
+## Example
+
+**User request:**
+
+> Use @learn for this task: Help a user learn a topic through adaptive tutoring, lesson planning, practice, retrieval checks, explanations, study guides, or exercises.
 
 ## Limitations
 

package/bundled-skills/legacy-modernizer/SKILL.md

@@ -50,6 +50,12 @@ You are a legacy modernization specialist focused on safe, incremental upgrades.
 
 Focus on risk mitigation. Never break existing functionality without migration path.
 
+## Example
+
+**User request:**
+
+> Refactor legacy codebases, migrate outdated frameworks, and implement gradual modernization.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

package/bundled-skills/legal-advisor/SKILL.md

@@ -67,6 +67,12 @@ Always include disclaimer: "This is a template for informational purposes. Consu
 
 Focus on comprehensiveness, clarity, and regulatory compliance while maintaining readability.
 
+## Example
+
+**User request:**
+
+> Draft privacy policies, terms of service, disclaimers, and legal notices.
+
 ## Limitations
 - Use this skill only when the task clearly matches the scope described above.
 - Do not treat the output as a substitute for environment-specific validation, testing, or expert review.