opencode-skills-collection 3.0.8 → 3.0.9

package/bundled-skills/multi-agent-architect/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: multi-agent-architect
+description: "Design and optimize production-grade multi-agent systems with LangGraph, LangChain, and DeepAgents for complex AI workflows."
+risk: safe
+source: community
+metadata:
+  category: ai-engineering
+  source_repo: pravin-python/antigravity-awesome-skills
+  source_type: community
+  date_added: "2025-05-07"
+  author: community
+  tags: [langgraph, langchain, multi-agent, orchestration, deepagents, rag, tool-calling]
+  tools: [claude, cursor, gemini]
+  license: "MIT"
+  license_source: "https://github.com/pravin-python/antigravity-awesome-skills/blob/main/LICENSE"
+---
+
+
+# Multi-Agent Architect & Updater Skill
+
+## Overview
+
+This skill turns Claude into a Senior AI Multi-Agent Architect specialized in LangGraph, LangChain, and DeepAgents. It provides structured workflows for creating and updating production-grade multi-agent systems — including supervisor agents, planners, researchers, coders, and memory-backed autonomous pipelines. Use it whenever you need to design, build, debug, or scale any multi-agent AI system.
+
+If this skill adapts material from an external GitHub repository, declare both:
+
+- `source_repo: owner/repo`
+- `source_type: official` or `source_type: community`
+
+## When to Use This Skill
+
+- Use when you need to create a new agent or multi-agent workflow from scratch
+- Use when working with LangGraph state graphs, nodes, edges, or conditional routing
+- Use when the user asks about agent communication, memory systems, or tool-calling pipelines
+- Use when debugging or optimizing an existing LangChain/LangGraph agent system
+- Use when architecting supervisor, planner, research, coding, or validation agent roles
+- Use when integrating DeepAgents with hierarchical planning and delegation
+
+## How It Works
+
+### Step 1: Understand the Goal
+
+Before writing any code, clarify:
+- What is the **business objective** this agent system must achieve?
+- What **agent roles** are needed (supervisor, planner, researcher, coder, validator)?
+- What **tools** does each agent require?
+- What **memory** strategy is needed (Redis, Vector DB, LangChain Memory)?
+- What **communication protocol** connects agents (shared state, message passing)?
+
+### Step 2: Define the State Schema
+
+All agents share a typed state object passed through the graph:
+
+```python
+from typing import TypedDict
+
+class AgentState(TypedDict):
+    user_goal: str
+    tasks: list[str]
+    completed_tasks: list[str]
+    next_agent: str
+    context: dict
+    step_count: int          # guards against infinite loops
+    error: str | None
+```
+
+### Step 3: Define Agent Nodes
+
+Each agent is an **async function** that reads from state and returns an updated state:
+
+```python
+import logging
+from langchain_openai import ChatOpenAI
+
+logger = logging.getLogger(__name__)
+
+async def research_node(state: AgentState) -> AgentState:
+    logger.info("research_node: starting")
+    llm = ChatOpenAI(model="gpt-4o")
+    result = await llm.bind_tools(research_tools).ainvoke(state["user_goal"])
+    state["context"]["research"] = result.content
+    state["next_agent"] = "coder"
+    return state
+```
+
+### Step 4: Build the LangGraph
+
+Wire nodes together with edges and conditional routing:
+
+```python
+from langgraph.graph import StateGraph, END
+from langgraph.prebuilt import ToolNode
+
+def build_graph() -> StateGraph:
+    graph = StateGraph(AgentState)
+
+    graph.add_node("supervisor", supervisor_node)
+    graph.add_node("research",   research_node)
+    graph.add_node("coder",      coding_node)
+    graph.add_node("validator",  validation_node)
+    graph.add_node("tools",      ToolNode(all_tools))
+
+    graph.set_entry_point("supervisor")
+
+    graph.add_conditional_edges(
+        "supervisor",
+        route_next,
+        {"research": "research", "coder": "coder", "end": END}
+    )
+
+    graph.add_edge("research",  "supervisor")
+    graph.add_edge("coder",     "validator")
+    graph.add_edge("validator", "supervisor")
+
+    return graph.compile()
+
+def route_next(state: AgentState) -> str:
+    if state["step_count"] > 20:
+        return "end"
+    return state["next_agent"]
+```
+
+### Step 5: Add Memory
+
+```python
+from langchain_community.chat_message_histories import RedisChatMessageHistory
+
+def get_memory(session_id: str):
+    return RedisChatMessageHistory(
+        session_id=session_id,
+        url=os.getenv("REDIS_URL"),
+        ttl=3600
+    )
+```
+
+### Step 6: Run the Graph
+
+```python
+async def run(user_goal: str, session_id: str):
+    graph = build_graph()
+    initial_state = AgentState(
+        user_goal=user_goal,
+        tasks=[],
+        completed_tasks=[],
+        next_agent="supervisor",
+        context={},
+        step_count=0,
+        error=None,
+    )
+    return await graph.ainvoke(initial_state)
+```
+
+### Step 7: Expose via FastAPI (optional)
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class RunRequest(BaseModel):
+    goal: str
+    session_id: str
+
+@app.post("/run")
+async def run_agent(req: RunRequest):
+    result = await run(req.goal, req.session_id)
+    return {"result": result}
+```
+
+---
+
+## Updating an Existing Agent
+
+When the user wants to update or debug an existing agent, structure the response as:
+
+```
+## Existing Issue
+[Describe the current problem]
+
+## Root Cause
+[Identify why it's happening in the architecture]
+
+## Proposed Update
+[Outline the changes at architecture level]
+
+## Updated Code
+[Generate only the changed modules]
+
+## Migration Notes
+[What breaks, what's backward-compatible]
+
+## Performance Impact
+[Latency / token / memory delta]
+```
+
+---
+
+## Standard Folder Structure
+
+Always generate code in this layout:
+
+```
+multi_agent_system/
+├── agents/          # One file per agent role
+├── tools/           # Tool definitions and wrappers
+├── memory/          # Redis, VectorDB, LangChain memory helpers
+├── prompts/         # Prompt templates (one per agent)
+├── workflows/       # High-level orchestration logic
+├── graphs/          # LangGraph state + compiled graph definitions
+├── api/             # FastAPI routes (optional)
+├── configs/         # Config loader — no secrets in code
+├── tests/           # Unit + integration tests per agent
+└── main.py
+```
+
+---
+
+## Examples
+
+### Example 1: Research + Coding Multi-Agent Workflow
+
+```python
+# agents/research_agent.py
+async def research_node(state: AgentState) -> AgentState:
+    llm = ChatOpenAI(model="gpt-4o").bind_tools([web_search, rag_search])
+    response = await llm.ainvoke(
+        f"Research the following and return structured findings:\n{state['user_goal']}"
+    )
+    state["context"]["research"] = response.content
+    state["next_agent"] = "coder"
+    return state
+
+# agents/coding_agent.py
+async def coding_node(state: AgentState) -> AgentState:
+    llm = ChatOpenAI(model="gpt-4o").bind_tools([python_repl, github_tool])
+    response = await llm.ainvoke(
+        f"Given this research:\n{state['context']['research']}\n\nWrite production Python code."
+    )
+    state["context"]["code"] = response.content
+    state["next_agent"] = "validator"
+    return state
+```
+
+### Example 2: Supervisor with Dynamic Delegation
+
+```python
+# agents/supervisor_agent.py
+DELEGATION_PROMPT = """
+You are a supervisor. Given the current state, decide the next agent.
+Available agents: research, coder, validator, end.
+Respond with ONLY the agent name.
+
+Goal: {goal}
+Completed: {completed}
+Context keys available: {context}
+"""
+
+async def supervisor_node(state: AgentState) -> AgentState:
+    state["step_count"] += 1
+    llm = ChatOpenAI(model="gpt-4o")
+    decision = await llm.ainvoke(
+        DELEGATION_PROMPT.format(
+            goal=state["user_goal"],
+            completed=state["completed_tasks"],
+            context=list(state["context"].keys()),
+        )
+    )
+    next_agent = decision.content.strip().lower()
+    # Validate against allowlist before setting
+    allowed = {"research", "coder", "validator", "end"}
+    state["next_agent"] = next_agent if next_agent in allowed else "end"
+    return state
+```
+
+### Example 3: DeepAgents Reflection Loop
+
+```python
+async def reflection_node(state: AgentState) -> AgentState:
+    llm = ChatOpenAI(model="gpt-4o")
+    critique = await llm.ainvoke(
+        f"Evaluate this output critically:\n{state['context'].get('code', '')}\n"
+        "List any bugs, gaps, or improvements. Be concise."
+    )
+    state["context"]["critique"] = critique.content
+    state["next_agent"] = "coder" if "bug" in critique.content.lower() else "end"
+    return state
+```
+
+---
+
+## Best Practices
+
+- ✅ One agent = one responsibility — never combine planning + coding + testing in one node
+- ✅ Use `TypedDict` for all state schemas — enables type checking and graph validation
+- ✅ Bind only the tools each agent needs — reduces hallucinated tool calls
+- ✅ Always add a `step_count` guard to prevent infinite routing loops
+- ✅ Use `async`/`await` throughout — LangGraph supports async natively
+- ✅ Store all secrets in environment variables loaded via `os.getenv()`
+- ✅ Set TTLs on all Redis keys scoped to `session_id`
+- ✅ Log at every node entry and tool call for observability
+- ✅ Validate supervisor routing output against an allowlist of agent names
+- ❌ Don't hardcode API keys, model names, or Redis URLs
+- ❌ Don't share tool lists across agents that don't need them
+- ❌ Don't skip error handling — tool failures and empty LLM responses are common
+- ❌ Don't trust unvalidated LLM routing decisions — always check against an allowlist
+
+---
+
+## Limitations
+
+- This skill does not replace environment-specific testing, load testing, or security review before production deployment.
+- Generated LangGraph code targets the current stable API — always verify method signatures against your installed version (`pip show langgraph`).
+- Stop and ask for clarification if the agent's goal, tool permissions, or routing logic is ambiguous before generating a full architecture.
+- DeepAgents integration patterns assume the library is installed and configured in the target environment.
+
+---
+
+## Security & Safety Notes
+
+- Never expose API keys in generated code. All secrets must use environment variables:
+  ```python
+  OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")   # ✅ correct
+  OPENAI_API_KEY = "sk-..."                        # ❌ never do this
+  ```
+- Always validate and sanitize user inputs before injecting them into agent prompts — treat all user input as untrusted.
+- Add a permission layer before allowing agents to execute shell commands or write to filesystems.
+- If generating a Python REPL tool node, document that it must only run in a sandboxed, isolated environment.
+  <!-- security-allowlist: python_repl tool examples are for sandboxed execution environments only -->
+- For production deployments, add rate-limit handling and exponential backoff on all LLM and external API calls.
+- Scope all Redis session keys to `session_id` and set a TTL to prevent memory leaks across sessions.
+
+---
+
+## Common Pitfalls
+
+- **Problem:** Agent loops indefinitely between supervisor and sub-agents  
+  **Solution:** Add `step_count: int` to state; return `"end"` in `route_next()` when `step_count > N`
+
+- **Problem:** Supervisor routes to a non-existent agent name  
+  **Solution:** Validate the LLM's routing output against a hardcoded allowlist before setting `next_agent`
+
+- **Problem:** Memory leaks across user sessions  
+  **Solution:** Scope Redis keys to `session_id` and always set a TTL (`ttl=3600`)
+
+- **Problem:** Tool results are ignored by the next agent  
+  **Solution:** Always write tool output into `state["context"]` and confirm the next node reads it
+
+- **Problem:** Agents share too many tools and hallucinate wrong tool calls  
+  **Solution:** Use `.bind_tools([only_relevant_tools])` per agent instead of a global tool list
+
+- **Problem:** Graph fails silently on API rate limits  
+  **Solution:** Wrap LLM calls in retry logic with exponential backoff using `tenacity`
+
+---
+
+## Related Skills
+
+- `@langchain-rag` - When you need retrieval-augmented generation pipelines specifically
+- `@fastapi-backend` - When deploying agent systems as production REST APIs
+- `@python-async` - When deepening async/await patterns used throughout agent nodes

package/bundled-skills/production-audit/SKILL.md

@@ -2,7 +2,7 @@
 name: production-audit
 description: "Audit a shipped repo for production-readiness gaps across RLS, webhooks, secrets, grants, Stripe idempotency, mobile UX, and deployment health."
 category: security
-risk: safe
+risk: critical
 source: community
 source_repo: commitshow/production-audit
 source_type: community
@@ -22,7 +22,7 @@ A skill that runs an external audit on a shipped repo's deployed state — live
 
 This is **complementary** to in-session security skills (`security-review`, OWASP-style, VibeSec, Trail of Bits). Those scan the editor buffer at write-time. This scans the deployed product after you commit. Different timing, different inputs, different findings. Run both for serious launches.
 
-The skill wraps the [commit.show](https://commit.show) audit engine via the public CLI (`npx commitshow audit . --json`). Stable JSON envelope (`schema_version: "1"`, additive-only). Writes a `.commitshow/audit.{md,json}` sidecar so future agent sessions can read prior state without re-running the engine.
+The skill wraps the [commit.show](https://commit.show) audit engine via the public CLI (`npx commitshow@0.3.23 audit . --json`). Stable JSON envelope (`schema_version: "1"`, additive-only). Writes a `.commitshow/audit.{md,json}` sidecar so future agent sessions can read prior state without re-running the engine.
 
 ## When to Use This Skill
 
@@ -42,11 +42,11 @@ The skill wraps the [commit.show](https://commit.show) audit engine via the publ
 
 ### Step 1: Run the audit
 
-From the repo root. The CLI is pinned to a known-good range (an attacker-pushed `0.4.x` won't be picked up silently — bumping the floor is a deliberate edit), the sidecar directory is created up-front, and stderr is split off so install/deprecation warnings can't corrupt the JSON envelope:
+From the repo root. The CLI is pinned to an exact reviewed version so future npm releases are not selected silently. Because `npx` downloads and runs npm package code locally with the current user's permissions, run it only after the user explicitly approves this external execution and only in a repository where local files and environment variables are safe for that process to access. The sidecar directory is created up-front, and stderr is split off so install/deprecation warnings can't corrupt the JSON envelope:
 
 ```bash
 mkdir -p .commitshow
-npx commitshow@^0.3.23 audit . --json \
+npx commitshow@0.3.23 audit . --json \
   > .commitshow/audit.json \
   2> .commitshow/audit.stderr.log
 ```
@@ -57,7 +57,7 @@ If the user pointed at a remote URL instead of `.`, swap `.` for the URL — kee
 
 ```bash
 mkdir -p .commitshow
-npx commitshow@^0.3.23 audit github.com/owner/repo --json \
+npx commitshow@0.3.23 audit github.com/owner/repo --json \
   > .commitshow/audit.json \
   2> .commitshow/audit.stderr.log
 ```
@@ -111,7 +111,7 @@ After applying a fix, suggest re-running with `--refresh` (same canonical form a
 
 ```bash
 mkdir -p .commitshow
-npx commitshow@^0.3.23 audit . --json --refresh \
+npx commitshow@0.3.23 audit . --json --refresh \
   > .commitshow/audit.json \
   2> .commitshow/audit.stderr.log
 ```
@@ -122,7 +122,7 @@ npx commitshow@^0.3.23 audit . --json --refresh \
 
 ```bash
 mkdir -p .commitshow
-npx commitshow@^0.3.23 audit . --json \
+npx commitshow@0.3.23 audit . --json \
   > .commitshow/audit.json \
   2> .commitshow/audit.stderr.log
 ```
@@ -172,7 +172,8 @@ Find the file path in the bullet, read it, confirm the gap matches.
 
 ## Security & Safety Notes
 
-- The skill executes `npx commitshow@latest audit ...` which is a network call to a public API at `https://api.commit.show` (proxied to Supabase Edge Functions). No credentials are sent — anonymous usage subject to per-IP / per-URL / global rate limits.
+- The skill executes `npx commitshow@0.3.23 audit ...`, which downloads and runs that exact npm package version locally, then calls the public API at `https://api.commit.show` (proxied to Supabase Edge Functions). Do not replace the exact version with `latest` or a semver range during normal use.
+- Treat the CLI as external code with local process privileges. It must not be run in repositories containing secrets or sensitive uncommitted files unless the user has explicitly accepted that risk. No credentials are intentionally sent to the API, but the local process can access files and environment variables available to the current user.
 - The CLI writes `.commitshow/audit.{md,json}` in the current working directory. These files are safe to commit (no secrets) but conventionally gitignored as transient artifacts.
 - The audit engine **only reads** public GitHub signals. It does not modify the user's repo or push commits.
 - All per-finding fix proposals must be shown as diffs and approved by the user before any edit. Never apply without explicit confirmation.

package/bundled-skills/rich-elicitation/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: rich-elicitation
+description: "Asks clarifying questions in multiple rounds before starting ambiguous tasks. Fires when 2+ task dimensions each have 3+ viable answers."
+category: productivity
+risk: none
+source: self
+source_type: self
+date_added: "2026-05-07"
+author: abubakar
+tags: [elicitation, clarifying-questions, ambiguity, multi-round, prompt-engineering]
+tools: [antigravity]
+---
+
+# Rich Elicitation Skill
+
+## Overview
+
+This skill governs how Antigravity resolves task ambiguity before starting work. When a user's request has too many unanswered dimensions — each with several reasonable answers — Antigravity asks targeted clarifying questions across multiple rounds rather than silently picking defaults.
+
+The goal is a correct first draft, not a generic answer that requires three revision cycles. Rounds are capped at three; anything still unclear after Round 3 gets a stated assumption and Antigravity proceeds.
+
+---
+
+## When to Use This Skill
+
+- Use when a request has 2 or more dimensions that are ambiguous and each has 3+ viable options
+- Use when the user's likely intent is unclear across scope, audience, tone, format, or strategy
+- Use when an early answer would meaningfully change the structure or direction of the output
+- Use when working on writing, planning, design, recommendations, or creative tasks with open-ended scope
+- Use when a Round 1 answer unlocks a new set of meaningful choices that need resolving before proceeding
+
+Do **not** trigger for:
+- Simple factual lookups or math
+- Clearly scoped requests with a single obvious interpretation
+- Minor unknowns where a safe default exists
+
+---
+
+## How It Works
+
+### Step 1: Run the Trigger Checklist
+
+Before starting any task, mentally check how many of these apply:
+
+| Signal | Action |
+|---|---|
+| Multiple valid output formats | Ask about format |
+| Audience is unknown | Ask about audience |
+| Tone is ambiguous | Ask about tone |
+| Scope could be narrow or broad | Ask about depth/length |
+| Technical vs. simple treatment unclear | Ask about technical level |
+| Multiple strategic directions exist | Ask which direction |
+| User's constraints are unknown | Ask about constraints |
+
+**If 2+ rows apply → trigger this skill.**
+
+### Step 2: Ask Round 1 Questions
+
+Ask up to 3 questions using `ask_user_input_v0`. Group related questions in a single call. Lead with 1–2 sentences explaining why you're asking. Mark one option per question as **(Recommended)**.
+
+### Step 3: Re-run the Checklist
+
+After Round 1 answers, re-run the checklist on what's still unresolved. If 2+ rows still apply, run Round 2. Otherwise, proceed.
+
+### Step 4: Run Follow-up Rounds (if needed)
+
+| Round | Purpose | Max questions |
+|---|---|---|
+| Round 1 | Blocking questions — shape the entire output | 3 |
+| Round 2 | Follow-ups unlocked by Round 1 answers | 3 |
+| Round 3 | Final details — use sparingly | 2 |
+
+Transition between rounds naturally. Don't announce "Round 2" mechanically. Use phrasing like:
+> "Got it — that helps a lot. One more thing before I start:"
+
+### Step 5: Proceed
+
+After Round 3 (or earlier, if enough context exists), state any remaining assumptions briefly and begin the task.
+
+---
+
+## Examples
+
+### Example 1: Multi-Round — Investor Pitch Deck
+
+**User:** "Help me create a presentation for my project."
+
+**Round 1** — Three blocking questions:
+
+```
+Framing: "This could go a lot of different ways. Quick questions before I start:"
+
+Q1: Who is the audience?
+  - Internal team / colleagues
+  - External clients or partners
+  - Investors or stakeholders (Recommended)
+  - General / public audience
+
+Q2: What's the primary goal?
+  - Inform and update
+  - Persuade and drive a decision (Recommended)
+  - Teach or explain a concept
+  - Pitch and raise funding
+
+Q3: How much content do you already have?
+  - Starting from scratch
+  - Rough notes or an outline (Recommended)
+  - Full draft — just needs polish
+  - Previous version to update
+```
+
+*User answers: Investors | Pitch | Rough notes → Round 2 is warranted.*
+
+**Round 2** — Unlocked by Round 1:
+
+```
+Framing: "Perfect — investor pitch it is. A couple more things:"
+
+Q1: What stage is this raise?
+  - Pre-seed / idea stage
+  - Seed round (Recommended)
+  - Series A or later
+  - Strategic partnership / grant
+
+Q2: How long should the deck be?
+  - Short and punchy, 8–10 slides (Recommended)
+  - Standard, 12–15 slides
+  - Comprehensive, 20+ slides
+```
+
+*No Round 3 needed — proceed.*
+
+---
+
+### Example 2: Single-Round — Business Email
+
+**User:** "Write a business email to follow up on a proposal."
+
+**Round 1 only:**
+
+```
+Framing: "Two quick questions to nail the tone:"
+
+Q1: What tone should this email strike?
+  - Formal and professional (Recommended)
+  - Friendly but direct
+  - Urgent and firm
+  - Warm and relationship-focused
+
+Q2: What's the primary goal?
+  - Request action / get a response (Recommended)
+  - Share information only
+  - Repair or maintain the relationship
+  - Negotiate or push back
+```
+
+*Enough context. No Round 2 needed.*
+
+---
+
+## Best Practices
+
+- ✅ Always mark one option per question as **(Recommended)**
+- ✅ Lead with a 1–2 sentence framing before the question widget
+- ✅ Group up to 3 related questions in a single `ask_user_input_v0` call
+- ✅ Re-evaluate after each round — stop as soon as you have enough context
+- ✅ Use `single_select` for mutually exclusive choices, `multi_select` when combinations are valid
+- ✅ State remaining assumptions explicitly before proceeding after Round 3
+- ❌ Don't ask 6 separate question calls when 2 grouped calls would do
+- ❌ Don't mark two options as Recommended in the same question
+- ❌ Don't use vague option labels like "Other" or "It depends" without elaborating
+- ❌ Don't mechanically label rounds in the UI ("Round 1:", "Round 2:")
+- ❌ Don't run a follow-up round for minor details that have safe defaults
+
+---
+
+## Limitations
+
+- This skill does not validate whether the user's answers are internally consistent — it trusts them as given.
+- Round structure is a guideline, not a rigid contract; judgment is required on when to stop.
+- Works best with `ask_user_input_v0` — in environments without that tool, question quality may degrade.
+- Does not handle tasks where ambiguity can only be resolved by fetching external information (e.g., reading a file the user hasn't uploaded).
+- Not designed for real-time or high-latency-sensitive workflows where any question overhead is unacceptable.
+
+---
+
+## Security & Safety Notes
+
+This skill is pure reasoning — it issues no shell commands, reads no files, makes no network requests, and mutates no state. Risk level is `none`.
+
+No `npm run security:docs` review is required for this skill.
+
+---
+
+## Common Pitfalls
+
+- **Problem:** Antigravity asks one good question, gets an answer, then proceeds without checking if new unknowns emerged.
+  **Solution:** Always re-run the trigger checklist mentally after each round before deciding to proceed.
+
+- **Problem:** All options in a question look equally valid so Antigravity marks none as Recommended.
+  **Solution:** Pick the option that works for most users or is lowest-risk and mark it. "No preference" is rarely true.
+
+- **Problem:** Antigravity runs 4+ rounds trying to eliminate every unknown.
+  **Solution:** Hard cap at 3 rounds. After Round 3, state assumptions and proceed.
+
+- **Problem:** Round 2 questions cover the same category as Round 1 (e.g., tone again).
+  **Solution:** Each round should unlock new dimensions, not re-ask resolved ones.
+
+---
+
+## Related Skills
+
+- `@ask-user-questions` — Single-round elicitation with recommended options. Use that skill for simpler tasks; use rich-elicitation when answers to early questions open up new meaningful choices.

package/bundled-skills/skill-writer/references/authoring-path.md

@@ -0,0 +1,26 @@
+# Authoring Path
+
+Use this path to create or update `SKILL.md` and supporting files.
+
+## SKILL.md checklist
+
+- Valid YAML frontmatter with `name` and trigger-rich `description`.
+- Clear title.
+- Short purpose statement.
+- Task routing or ordered steps.
+- Output contract.
+- `## When to Use`.
+- `## Limitations`.
+
+## Supporting files
+
+Add `references/` when optional detail would make SKILL.md too long or distract from routing.
+Add `scripts/` only when deterministic execution is useful and safer than rewriting code each time.
+Add `assets/` only for files used directly in produced outputs.
+
+## Editing rules
+
+- Prefer small, scoped updates over rewrites.
+- Preserve existing naming conventions.
+- Keep examples copy-pasteable when commands are included.
+- Avoid unsafe install, credential, or destructive command guidance unless prerequisites and warnings are explicit.