opencode-skills-collection 3.0.46 → 3.0.48

package/bundled-skills/ecl-harness-engineer/references/observability-templates.md

@@ -0,0 +1,315 @@
+# Observability Templates
+
+Templates for agent observability infrastructure.
+
+Advanced profile only. Load this reference only when the user explicitly requests agent execution
+traces, observability hooks, metrics, or debugging of long-running agent sessions. Do not create
+`harness/trace` or observability hooks as part of the default core harness.
+
+## Trace Format
+
+Standard format for recording agent execution sessions.
+
+```go
+// harness/trace/format.go
+package trace
+
+import (
+	"encoding/json"
+	"os"
+	"time"
+)
+
+// AgentTrace captures a complete agent execution session
+type AgentTrace struct {
+	SessionID    string          `json:"session_id"`
+	AgentType    string          `json:"agent_type"`
+	StartTime    time.Time       `json:"start_time"`
+	EndTime      time.Time       `json:"end_time"`
+	Prompt       string          `json:"prompt"`
+	SystemPrompt string          `json:"system_prompt,omitempty"`
+	WorkingDir   string          `json:"working_dir"`
+	Messages     []MessageTrace  `json:"messages"`
+	ToolCalls    []ToolTrace     `json:"tool_calls"`
+	TokenUsage   TokenUsage      `json:"token_usage"`
+	Outcome      Outcome         `json:"outcome"`
+	Result       string          `json:"result,omitempty"`
+	Error        string          `json:"error,omitempty"`
+	Metadata     map[string]any  `json:"metadata,omitempty"`
+}
+
+type MessageTrace struct {
+	ID        string    `json:"id,omitempty"`
+	Role      string    `json:"role"`
+	Content   string    `json:"content"`
+	Timestamp time.Time `json:"timestamp"`
+}
+
+type ToolTrace struct {
+	ID        string          `json:"id"`
+	Tool      string          `json:"tool"`
+	Input     json.RawMessage `json:"input"`
+	Output    string          `json:"output"`
+	Duration  time.Duration   `json:"duration"`
+	Timestamp time.Time       `json:"timestamp"`
+	IsError   bool            `json:"is_error"`
+	ErrCode   int             `json:"err_code,omitempty"`
+}
+
+type TokenUsage struct {
+	InputTokens  int64 `json:"input_tokens"`
+	OutputTokens int64 `json:"output_tokens"`
+	TotalTokens  int64 `json:"total_tokens"`
+}
+
+type Outcome string
+
+const (
+	OutcomeSuccess      Outcome = "success"
+	OutcomeError        Outcome = "error"
+	OutcomeTimeout      Outcome = "timeout"
+	OutcomeCancelled    Outcome = "cancelled"
+	OutcomeMaxTurns     Outcome = "max_turns"
+	OutcomeMaxToolCalls Outcome = "max_tool_calls"
+)
+
+// TraceBuilder constructs traces incrementally
+type TraceBuilder struct {
+	trace AgentTrace
+}
+
+func NewTraceBuilder(sessionID, agentType string) *TraceBuilder {
+	return &TraceBuilder{
+		trace: AgentTrace{
+			SessionID: sessionID,
+			AgentType: agentType,
+			StartTime: time.Now(),
+			Messages:  make([]MessageTrace, 0),
+			ToolCalls: make([]ToolTrace, 0),
+			Metadata:  make(map[string]any),
+		},
+	}
+}
+
+func (b *TraceBuilder) AddMessage(msg MessageTrace) { b.trace.Messages = append(b.trace.Messages, msg) }
+func (b *TraceBuilder) AddToolCall(tc ToolTrace)     { b.trace.ToolCalls = append(b.trace.ToolCalls, tc) }
+
+func (b *TraceBuilder) Build() AgentTrace {
+	b.trace.EndTime = time.Now()
+	return b.trace
+}
+
+func (t *AgentTrace) Export(path string) error {
+	data, err := json.MarshalIndent(t, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, data, 0644)
+}
+
+func Load(path string) (*AgentTrace, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var trace AgentTrace
+	return &trace, json.Unmarshal(data, &trace)
+}
+```
+
+## Self-Test Framework
+
+Framework for testing agent behavior with validation.
+
+```go
+// harness/selftest/runner.go
+package selftest
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// TestCase defines a single agent test
+type TestCase struct {
+	Name        string                `json:"name"`
+	Category    string                `json:"category"`
+	Prompt      string                `json:"prompt"`
+	InitFiles   map[string]string     `json:"init_files,omitempty"`
+	Timeout     time.Duration         `json:"timeout"`
+	MaxTurns    int                   `json:"max_turns,omitempty"`
+	Expected    *Expectations         `json:"expected,omitempty"`
+	Validators  []Validator           `json:"-"`
+}
+
+type Expectations struct {
+	Files     map[string]FileExpectation `json:"files,omitempty"`
+	ToolCalls []ToolCallExpectation      `json:"tool_calls,omitempty"`
+}
+
+type FileExpectation struct {
+	MustExist      bool     `json:"must_exist"`
+	MustContain    []string `json:"must_contain,omitempty"`
+	MustNotContain []string `json:"must_not_contain,omitempty"`
+}
+
+type ToolCallExpectation struct {
+	Tool         string `json:"tool"`
+	MustOccur    bool   `json:"must_occur,omitempty"`
+	MustNotOccur bool   `json:"must_not_occur,omitempty"`
+}
+
+type Validator func(result *AgentResult) error
+
+type AgentResult struct {
+	TestName  string            `json:"test_name"`
+	Success   bool              `json:"success"`
+	Error     string            `json:"error,omitempty"`
+	Duration  time.Duration     `json:"duration"`
+	ToolCalls []ToolCallRecord  `json:"tool_calls"`
+}
+
+type ToolCallRecord struct {
+	Tool     string          `json:"tool"`
+	Input    json.RawMessage `json:"input"`
+	Output   string          `json:"output"`
+	IsError  bool            `json:"is_error"`
+	Duration time.Duration   `json:"duration"`
+}
+
+type Runner struct {
+	WorkDir        string
+	DefaultTimeout time.Duration
+}
+
+func NewRunner(workDir string) *Runner {
+	return &Runner{WorkDir: workDir, DefaultTimeout: 2 * time.Minute}
+}
+
+func (r *Runner) Run(ctx context.Context, tc TestCase) (*AgentResult, error) {
+	result := &AgentResult{
+		TestName:  tc.Name,
+		ToolCalls: make([]ToolCallRecord, 0),
+	}
+	start := time.Now()
+	defer func() { result.Duration = time.Since(start) }()
+
+	// TODO: Integrate with actual agent execution
+	return result, fmt.Errorf("not yet integrated with agent")
+}
+```
+
+## Observability Hook
+
+Hook that records tool calls for analysis and replay.
+
+```go
+// hooks/observability/observability.go
+package observability
+
+import (
+	"encoding/json"
+	"sync"
+	"time"
+)
+
+type ToolTrace struct {
+	Tool       string          `json:"tool"`
+	Input      json.RawMessage `json:"input"`
+	Output     string          `json:"output"`
+	IsError    bool            `json:"is_error"`
+	Duration   time.Duration   `json:"duration"`
+	Timestamp  time.Time       `json:"timestamp"`
+}
+
+// TraceRecorder collects tool traces
+type TraceRecorder struct {
+	mu        sync.RWMutex
+	traces    []ToolTrace
+	sessionId string
+	startTime time.Time
+}
+
+func NewTraceRecorder(sessionId string) *TraceRecorder {
+	return &TraceRecorder{
+		traces:    make([]ToolTrace, 0),
+		sessionId: sessionId,
+		startTime: time.Now(),
+	}
+}
+
+func (r *TraceRecorder) Record(trace ToolTrace)  {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.traces = append(r.traces, trace)
+}
+
+func (r *TraceRecorder) GetTraces() []ToolTrace {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	result := make([]ToolTrace, len(r.traces))
+	copy(result, r.traces)
+	return result
+}
+
+func (r *TraceRecorder) ExportJSON() ([]byte, error) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	return json.MarshalIndent(map[string]any{
+		"session_id": r.sessionId,
+		"start_time": r.startTime,
+		"end_time":   time.Now(),
+		"traces":     r.traces,
+	}, "", "  ")
+}
+
+// Summary returns aggregate statistics
+func (r *TraceRecorder) Summary() TraceSummary {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	summary := TraceSummary{
+		TotalCalls: len(r.traces),
+		ToolCounts: make(map[string]int),
+	}
+	for _, t := range r.traces {
+		summary.ToolCounts[t.Tool]++
+		if t.IsError {
+			summary.TotalErrors++
+		}
+		summary.TotalDuration += t.Duration
+	}
+	return summary
+}
+
+type TraceSummary struct {
+	TotalCalls    int            `json:"total_calls"`
+	TotalErrors   int            `json:"total_errors"`
+	TotalDuration time.Duration  `json:"total_duration"`
+	ToolCounts    map[string]int `json:"tool_counts"`
+}
+```
+
+## Integration Pattern
+
+To wire the observability hook into an existing agent:
+
+```go
+// In agent initialization:
+recorder := observability.NewTraceRecorder(sessionId)
+hook := observability.NewObservabilityHook(recorder)
+
+// Register as PostToolUse hook
+agent.AddPostToolUseHook(hook)
+
+// After agent completes:
+traces := recorder.GetTraces()
+summary := recorder.Summary()
+summary.Print()
+
+// Export for analysis
+data, _ := recorder.ExportJSON()
+os.WriteFile("trace.json", data, 0644)
+```

package/bundled-skills/efficient-web-research/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: efficient-web-research
+risk: safe
+description: >
+  Protocol for token-efficient web research. Use when accessing URLs, GitHub repos, or running search queries. Prevents full-page fetching waste.
+---
+
+# Efficient Web Research Skill
+
+A protocol for accessing web content in the most token-efficient, accurate, and structured way —
+using the right tool at the right depth, and stopping as soon as the question is answerable.
+
+---
+
+## Core Principle
+
+> **Fetch the minimum needed to answer. Skim before you dive. Stop when you can answer.**
+
+Every unnecessary fetch wastes tokens and adds noise. This skill enforces a layered approach
+where you escalate fetch depth only when shallower layers fail.
+
+---
+
+## Step 1 — Classify the Input
+
+Before fetching anything, identify what kind of input you received:
+
+| Input Type | Example | Go To |
+|---|---|---|
+| GitHub repo URL | `github.com/user/repo` | [GitHub Protocol](#github-protocol) |
+| Specific page URL | `docs.python.org/3/library/os` | [URL Protocol](#url-protocol) |
+| Topic / query (no URL) | "how does RAFT consensus work" | [Search Protocol](#search-protocol) |
+| Multiple URLs | List of links | [Multi-URL Protocol](#multi-url-protocol) |
+| PDF / file link | `.pdf`, `.txt`, `.md` URL | [File Protocol](#file-protocol) |
+
+---
+
+## GitHub Protocol
+
+Use when input is a GitHub URL (repo, file, PR, issue, etc.)
+
+### Step 1 — Parse the URL
+
+```
+github.com/{owner}/{repo}                → Repo root
+github.com/{owner}/{repo}/tree/{branch}  → Directory
+github.com/{owner}/{repo}/blob/{branch}/{path} → Single file
+github.com/{owner}/{repo}/issues/{n}     → Issue
+github.com/{owner}/{repo}/pull/{n}       → Pull request
+```
+
+### Step 2 — Use GitHub API (preferred over scraping)
+
+Always prefer the GitHub API. It returns clean JSON — no HTML parsing needed.
+
+```
+# Repo metadata (name, description, language, stars, topics)
+GET https://api.github.com/repos/{owner}/{repo}
+
+# File tree (see what files exist — very cheap)
+GET https://api.github.com/repos/{owner}/{repo}/git/trees/{ref}?recursive=1
+
+# Single file content (base64 encoded)
+GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={ref}
+
+# README only (usually enough to understand the repo)
+GET https://api.github.com/repos/{owner}/{repo}/readme
+```
+
+### Step 3 — Layered Fetch for Repos
+
+```
+Layer 1 (always do first):
+  → Fetch repo metadata + README only
+  → Can you answer the user's question now? YES → STOP. NO → continue.
+
+Layer 2 (only if needed):
+  → Fetch file tree to understand structure
+  → Identify the 1-3 most relevant files based on the question
+  → Can you answer now? YES → STOP. NO → continue.
+
+Layer 3 (last resort):
+  → Fetch specific relevant files only (never fetch all files)
+  → Prioritize: main entry point, config files, key modules
+```
+
+### Token Rules for GitHub
+
+- README alone answers ~70% of "what does this repo do" questions — always try it first
+- Never fetch more than 3 files in a single research turn
+- If a file exceeds ~300 lines, read only the top (imports + class/function signatures)
+- Decode base64 content from API before passing to context
+
+---
+
+## URL Protocol
+
+Use when the user gives a specific non-GitHub URL (docs, articles, blogs, etc.)
+
+### Step 1 — Assess the URL type
+
+| Site type | Likely works with | Notes |
+|---|---|---|
+| Static docs / MDN / ReadTheDocs | `read_url_content` | Fast, clean, cheap |
+| News articles / blogs | `read_url_content` | Usually fine |
+| SPAs / React/Next.js apps | `browser_subagent` | JS-rendered |
+| Auth-gated pages | `browser_subagent` | Needs login |
+| Raw GitHub files (raw.githubusercontent) | `read_url_content` | Direct text |
+
+### Step 2 — Layered Fetch
+
+```
+Layer 1 — Skim
+  → Fetch the URL with read_url_content
+  → Read only headings (H1, H2, H3) and first paragraph
+  → Does this page contain what the user needs? NO → try a different URL or search. YES → continue.
+
+Layer 2 — Targeted Extract
+  → If the page has anchor links (e.g. /docs/page#section), fetch with the anchor
+  → Extract only the relevant section (200–500 tokens max)
+  → Can you answer? YES → STOP.
+
+Layer 3 — Full Fetch
+  → Fetch full page, strip boilerplate (nav, footer, ads, cookie banners, sidebars)
+  → Cap at 2000 tokens. Summarize before passing to answer.
+
+Layer 4 — Browser Subagent (last resort only)
+  → Use ONLY if read_url_content returns empty, garbled, or JS-placeholder content
+  → Instruct subagent: "Navigate to [URL], wait for content to load, extract [specific section]"
+  → Do NOT use browser_subagent for static pages — it's expensive
+```
+
+### What to Strip from Fetched Pages
+
+Always remove before using fetched content:
+- Navigation menus and breadcrumbs
+- Cookie banners and GDPR notices
+- "Related articles" / "You might also like" blocks
+- Footer content (copyright, links)
+- Social share buttons
+- Ads and sponsored content
+
+Extract and keep:
+- Main article / documentation body
+- Code blocks
+- Tables with data
+- Numbered steps or procedures
+
+---
+
+## Search Protocol
+
+Use when the user gives a topic, question, or query — not a specific URL.
+
+### Step 1 — Sharpen the Query Before Searching
+
+Do NOT search the raw user query. Transform it first:
+
+```
+Raw: "how to deploy fastapi on aws"
+Sharpened: "fastapi AWS deployment tutorial 2024"
+
+Raw: "python async vs threads"
+Sharpened: "Python asyncio vs threading performance comparison"
+
+Raw: "best way to structure react project"
+Sharpened: "React project folder structure best practices"
+```
+
+**Query sharpening rules:**
+- Add specificity: version numbers, technology names, "tutorial" / "guide" / "comparison"
+- Add recency if relevant: current year
+- Remove filler words: "how do I", "what is the", "can you explain"
+- For code questions: add the language + framework name explicitly
+
+### Step 2 — Search and Select
+
+```
+1. Run search_web with the sharpened query
+2. Get results (titles + snippets)
+3. Scan titles + snippets ONLY — do not fetch yet
+4. Pick the TOP 1-2 most relevant results (max 3 in complex cases)
+5. Skip results from: forums (if docs exist), aggregator blogs, paywalled sites
+6. Prefer: official docs, GitHub repos, well-known tech blogs, academic sources
+```
+
+### Step 3 — Fetch Selected Results
+
+Apply the URL Protocol (above) to each selected URL.
+Process results one at a time — only fetch the second URL if the first didn't answer the question.
+
+### Token Rules for Search
+
+- Never read more than 3 URLs per search query
+- If the snippet already contains the answer → do NOT fetch the full page, use the snippet
+- For factual questions (dates, names, simple facts) → snippet is usually enough
+- For procedural questions (how to do X) → fetch 1 relevant page, targeted section only
+
+---
+
+## Multi-URL Protocol
+
+Use when the user provides a list of URLs to compare or summarize.
+
+```
+1. Skim all URLs first (Layer 1 fetch for each)
+2. Group by relevance to the user's question
+3. Deep-fetch only the most relevant 1-3 URLs
+4. Summarize each in 3-5 sentences before combining
+5. Never dump raw content from multiple pages — always summarize per-source first
+```
+
+---
+
+## File Protocol
+
+Use when URL points directly to a file (PDF, .txt, .md, .csv, etc.)
+
+- `.md` / `.txt` / `.csv` → `read_url_content` works directly, read full content
+- `.pdf` → Use browser_subagent or a PDF extraction tool; extract text only
+- `.json` / `.yaml` → `read_url_content`, parse structure, summarize schema + key values
+- Large files (>500 lines) → Read first 100 lines + last 20 lines + search for relevant sections
+
+---
+
+## Anti-Patterns (Never Do These)
+
+| Anti-pattern | Why it's bad | Do this instead |
+|---|---|---|
+| Fetching full page for a simple fact | Wastes 1000s of tokens | Use snippet or targeted anchor |
+| Using browser_subagent for static sites | Very expensive | Use read_url_content first |
+| Searching with the raw user query | Vague results | Sharpen query first |
+| Fetching 5+ search results | Token explosion | Max 3, stop when answered |
+| Dumping raw HTML into context | Noisy, wasteful | Always strip to Markdown |
+| Fetching "just in case" | Unnecessary tokens | Only fetch what's needed to answer |
+| Re-fetching the same URL | Redundant | Cache result in context, reuse |
+| Fetching entire GitHub repo | Extremely wasteful | README + targeted files only |
+
+---
+
+## Decision Flowchart (Quick Reference)
+
+```
+Input received
+│
+├─ GitHub URL?
+│   ├─ Fetch README + metadata via API
+│   ├─ Answered? → STOP
+│   ├─ Need more? → Fetch file tree, pick 1-3 files
+│   └─ Still need more? → Fetch specific files only
+│
+├─ Specific URL?
+│   ├─ Try read_url_content → skim headings
+│   ├─ Answered? → STOP
+│   ├─ Need more? → Targeted section fetch
+│   ├─ Still need more? → Full fetch, stripped
+│   └─ JS-rendered / broken? → browser_subagent (last resort)
+│
+├─ Topic/query?
+│   ├─ Sharpen query
+│   ├─ search_web → scan snippets
+│   ├─ Snippet enough? → Answer from snippet, STOP
+│   ├─ Need more? → Fetch top 1 result (targeted)
+│   └─ Still need more? → Fetch top 2nd result (targeted)
+│
+└─ List of URLs?
+    ├─ Skim all (Layer 1 each)
+    ├─ Deep fetch top 1-3 relevant ones
+    └─ Summarize per-source, then combine
+```
+
+---
+
+## Output Format Rules
+
+After fetching, structure your response as:
+
+```
+Source: [URL or "Web search for: query"]
+Summary: [2-5 sentences of what was found]
+Answer: [Direct answer to user's question]
+Confidence: [High / Medium / Low — based on source quality]
+```
+
+For multiple sources:
+```
+Source 1: ...
+Source 2: ...
+Combined Answer: ...
+```
+
+Never output:
+- Raw HTML fragments
+- Full page dumps
+- Unattributed information
+- More than needed to answer the question
+
+---
+
+## Token Budget Guide
+
+| Operation | Approximate token cost | When to use |
+|---|---|---|
+| GitHub README fetch | ~300–800 tokens | Always first for repos |
+| GitHub API metadata | ~200 tokens | Always for repos |
+| Skim (headings only) | ~100–200 tokens | Always first for URLs |
+| Targeted section fetch | ~300–600 tokens | When skim isn't enough |
+| Full page fetch (stripped) | ~1000–2000 tokens | Only when targeted fails |
+| browser_subagent | ~2000–5000 tokens | Last resort only |
+| Search snippet scan | ~300–500 tokens | Always before fetching |
+
+**Rule of thumb:** If you're about to spend >2000 tokens on a fetch, ask yourself if there's a cheaper path first.
+
+---
+
+## Limitations
+
+- **JavaScript Reliance**: Standard fetching may not fully render Single Page Applications (SPAs). You must fallback to `browser_subagent` for these, which is slower and more expensive.
+- **Paywalls & Protections**: This skill cannot bypass CAPTCHAs, bot protections (e.g., strict Cloudflare rules), or hard paywalls.
+- **GitHub API Limits**: Frequent GitHub API requests without authentication may hit rate limits.

package/bundled-skills/environment-setup-guide/SKILL.md

@@ -86,7 +86,7 @@ Provide verification steps to ensure everything works:
 tmpdir="$(mktemp -d)"
 trap 'rm -rf "$tmpdir"' EXIT
 curl -fsSLo "$tmpdir/homebrew-install.sh" https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh
-sed -n '1,160p' "$tmpdir/homebrew-install.sh"
+cat "$tmpdir/homebrew-install.sh"  # review the full installer before executing
 /bin/bash "$tmpdir/homebrew-install.sh"
 
 # Install Node.js
@@ -102,7 +102,7 @@ sudo apt update
 tmpdir="$(mktemp -d)"
 trap 'rm -rf "$tmpdir"' EXIT
 curl -fsSLo "$tmpdir/nodesource-setup.sh" https://deb.nodesource.com/setup_20.x
-sed -n '1,160p' "$tmpdir/nodesource-setup.sh"
+cat "$tmpdir/nodesource-setup.sh"  # review the full installer before sudo
 sudo -E bash "$tmpdir/nodesource-setup.sh"
 sudo apt install -y nodejs
 \`\`\`

package/bundled-skills/evolution/SKILL.md

@@ -37,7 +37,7 @@ For reliable automatic triggering, use Claude Code hooks. Install with `--with-h
 tmpdir="$(mktemp -d)"
 trap 'rm -rf "$tmpdir"' EXIT
 curl -fsSLo "$tmpdir/makepad-skills-install.sh" https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh
-sed -n '1,160p' "$tmpdir/makepad-skills-install.sh"
+cat "$tmpdir/makepad-skills-install.sh"  # review the full installer before executing
 bash "$tmpdir/makepad-skills-install.sh" --with-hooks
 ```
 

package/bundled-skills/gitops-workflow/SKILL.md

@@ -144,7 +144,7 @@ brew install fluxcd/tap/flux
 tmpdir="$(mktemp -d)"
 trap 'rm -rf "$tmpdir"' EXIT
 curl -fsSLo "$tmpdir/flux-install.sh" https://fluxcd.io/install.sh
-sed -n '1,160p' "$tmpdir/flux-install.sh"
+cat "$tmpdir/flux-install.sh"  # review the full installer before sudo
 sudo bash "$tmpdir/flux-install.sh"
 
 # Bootstrap Flux

package/bundled-skills/linkerd-patterns/SKILL.md

@@ -76,7 +76,7 @@ brew install linkerd
 tmpdir="$(mktemp -d)"
 trap 'rm -rf "$tmpdir"' EXIT
 curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install -o "$tmpdir/linkerd-install.sh"
-sed -n '1,160p' "$tmpdir/linkerd-install.sh"
+cat "$tmpdir/linkerd-install.sh"  # review the full installer before executing
 sh "$tmpdir/linkerd-install.sh"
 
 # Validate cluster