natureco-cli 5.18.3 → 5.20.0

package/skills/token-optimization/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: token-optimization
+description: Optimize token usage with compression, truncation, and efficient prompting
+category: AI Agents
+---
+
+# Token Optimization
+
+## Overview
+Optimize token usage with compression, truncation, and efficient prompting. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply token optimization best practices
+- When establishing processes or standards for your workflow
+- When training team members on token optimization
+- When automating or optimizing token optimization tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply token optimization for my current project
+Assistant: I'll help you apply token optimization step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/tool-calling-patterns/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: tool-calling-patterns
+description: Implement tool calling with function schemas, parallel execution, and result handling
+category: AI Agents
+---
+
+# Tool Calling Patterns
+
+## Overview
+Implement tool calling with function schemas, parallel execution, and result handling. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply tool calling patterns best practices
+- When establishing processes or standards for your workflow
+- When training team members on tool calling patterns
+- When automating or optimizing tool calling patterns tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply tool calling patterns for my current project
+Assistant: I'll help you apply tool calling patterns step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/typescript-magician/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: typescript-magician
+description: Designs complex generic types, refactors `any` types to strict alternatives, creates type guards and utility types, and resolves TypeScript compiler errors. Use when the user asks about TypeScript (TS) types, generics, type inference, type guards, removing `any` types, strict typing, type errors, `infer`, `extends`, conditional types, mapped types, template literal types, branded/opaque types, or utility types like `Partial`, `Record`, `ReturnType`, and `Awaited`.
+metadata:
+  tags: typescript, types, generics, type-safety, advanced-typescript
+---
+
+## When to use
+
+Use this skill for:
+- TypeScript errors and type challenges
+- Eliminating `any` types from codebases
+- Complex generics and type inference issues
+- When strict typing is needed
+
+## Instructions
+
+When invoked:
+1. Run `tsc --noEmit` to capture the full error output before making changes
+2. Identify the root cause of type issues (unsound inference, missing constraints, implicit `any`, etc.)
+3. Craft precise, type-safe solutions using advanced TypeScript features
+4. Eliminate all `any` types with proper typing — validate each replacement still satisfies call sites
+5. Confirm the fix compiles cleanly with a second `tsc --noEmit` pass
+
+Capabilities include:
+- Advanced generics and conditional types
+- Template literal types and mapped types
+- Utility types and type manipulation
+- Brand types and nominal typing
+- Complex inference patterns
+- Variance and distribution rules
+- Module augmentation and declaration merging
+
+For every TypeScript challenge:
+- Explain the type theory behind the problem
+- Provide multiple solution approaches when applicable
+- Show before/after type representations
+- Include comprehensive type tests
+- Ensure full IntelliSense support
+
+## Quick Examples
+
+### Eliminating `any` with generics
+
+**Before**
+```ts
+function getProperty(obj: any, key: string): any {
+  return obj[key];
+}
+```
+
+**After**
+```ts
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+// getProperty({ name: "Alice" }, "name") → inferred as string ✓
+```
+
+### Narrowing an unknown API response
+
+**Before**
+```ts
+async function fetchUser(): Promise<any> {
+  const res = await fetch("/api/user");
+  return res.json();
+}
+```
+
+**After**
+```ts
+interface User { id: number; name: string }
+
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    "name" in value
+  );
+}
+
+async function fetchUser(): Promise<User> {
+  const res = await fetch("/api/user");
+  const data: unknown = await res.json();
+  if (!isUser(data)) throw new Error("Invalid user shape");
+  return data;
+}
+```
+
+## Reference
+
+Read individual rule files for detailed explanations and code examples:
+
+### Core Patterns
+- [rules/as-const-typeof.md](rules/as-const-typeof.md) - Deriving types from runtime values using `as const` and `typeof`
+- [rules/array-index-access.md](rules/array-index-access.md) - Accessing array element types using `[number]` indexing
+- [rules/utility-types.md](rules/utility-types.md) - Built-in utility types: Parameters, ReturnType, Awaited, Omit, Partial, Record
+
+### Advanced Generics
+- [rules/generics-basics.md](rules/generics-basics.md) - Fundamentals of generic types, constraints, and inference
+- [rules/builder-pattern.md](rules/builder-pattern.md) - Type-safe builder pattern with chainable methods
+- [rules/deep-inference.md](rules/deep-inference.md) - Achieving deep type inference with F.Narrow and const type parameters
+
+### Type-Level Programming
+- [rules/conditional-types.md](rules/conditional-types.md) - Conditional types for type-level if/else logic
+- [rules/infer-keyword.md](rules/infer-keyword.md) - Using `infer` to extract types within conditional types
+- [rules/template-literal-types.md](rules/template-literal-types.md) - String manipulation at the type level
+- [rules/mapped-types.md](rules/mapped-types.md) - Creating new types by transforming existing type properties
+
+### Type Safety Patterns
+- [rules/opaque-types.md](rules/opaque-types.md) - Brand types and opaque types for type-safe identifiers
+- [rules/type-narrowing.md](rules/type-narrowing.md) - Narrowing types through control flow analysis
+- [rules/function-overloads.md](rules/function-overloads.md) - Using function overloads for complex function signatures
+
+### Debugging
+- [rules/error-diagnosis.md](rules/error-diagnosis.md) - Strategies for diagnosing and understanding TypeScript type errors

package/skills/tzst/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: tzst
+description: Use when the user needs to create, extract, flatten, list, test, install, script, or troubleshoot `tzst` CLI workflows for `.tzst` or `.tar.zst` archives, including compression levels, streaming mode, extraction filters, conflict resolution, JSON output, or standalone binary setup, even if they describe the archive task without naming `tzst`.
+---
+
+Use this skill for the `tzst` command-line interface. Default to execution when the user clearly wants a real archive action and the required paths or archive names are already known.
+
+This skill is CLI-only. If the user is asking about Python code such as `from tzst import ...`, treat that as a general Python library or API documentation task instead of using this skill as the main guide.
+
+## When to Use
+
+Use this skill when the user:
+
+- mentions `.tzst` or `.tar.zst` archives
+- wants to create, extract, flatten, list, or test a `tzst` archive
+- needs help installing `tzst` or choosing CLI flags
+- wants machine-readable `tzst` output for scripting or automation
+- needs safe conflict handling or extraction filter guidance
+
+Do not use this skill for generic `tar`, `zip`, or Python API questions unless `tzst` is actually part of the request.
+
+## Preflight
+
+1. Check whether `tzst` is available with `tzst --version` or `tzst --help`.
+2. If it is missing, prefer one of these installation paths:
+   - `uv tool install tzst`
+   - `pip install tzst`
+   - a standalone release binary from <https://github.com/xixu-me/tzst/releases/latest> when the user does not want a Python installation
+3. Re-run `tzst --version` or `tzst --help` before doing real work.
+
+## Workflow
+
+1. Decide whether the request is execution or guidance.
+   Requests like "archive these files", "extract this backup", "list what is inside", "test this archive", or "install tzst" are execution intent.
+2. Choose the command that matches the request:
+   - `a`, `add`, `create` for archive creation
+   - `x`, `extract` for normal extraction with directory structure preserved
+   - `e`, `extract-flat` only when the user explicitly wants flattened output
+   - `l`, `list` for archive inspection
+   - `t`, `test` for integrity checks
+3. If the user wants to extract only a few members and the member names are uncertain, list first.
+4. Load [`references/cli-reference.md`](./references/cli-reference.md) when you need the command matrix, exact flag names, or copy-paste examples.
+
+## Safe Defaults
+
+- Prefer `x` over `e` unless flattening is explicitly requested.
+- Keep `--filter data` as the default extraction mode.
+- Use `--filter tar` only when the user needs standard tar-style compatibility.
+- Use `--filter fully_trusted` only when the user explicitly says the archive source is completely trusted.
+- Keep atomic archive creation enabled. Only reach for `--no-atomic` when the user explicitly wants it.
+- Prefer `--streaming` for large archives or memory-constrained environments.
+- For automation or pipelines, prefer `tzst --json --no-banner ...`.
+- For automated extraction, require an explicit non-interactive `--conflict-resolution` choice such as `replace_all`, `skip_all`, or `auto_rename_all`.
+- Do not combine `--json` with interactive conflict prompting.
+
+## Scripting Notes
+
+- Put global flags before the subcommand in examples, such as `tzst --json --no-banner l archive.tzst`.
+- Use exit codes in scripts: `0` for success, `1` for operation errors, `2` for argument parsing errors, and `130` for interruption.
+- When archive naming matters, tell the user that `tzst` may normalize a creation target to `.tzst` or `.tar.zst`.
+
+## Common Mistakes
+
+- Using `e` when the user expected the original directory structure to be preserved
+- Recommending `fully_trusted` for archives from an unknown or untrusted source
+- Forgetting an explicit conflict strategy for non-interactive extraction
+- Treating a Python API question as a CLI question
+- Guessing flags from `tar` habits instead of checking the bundled reference or the installed CLI help

package/skills/ubiquitous-language/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ubiquitous-language
+description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
+disable-model-invocation: true
+---
+
+# Ubiquitous Language
+
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
+
+## Process
+
+1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
+2. **Identify problems**:
+   - Same word used for different concepts (ambiguity)
+   - Different words used for the same concept (synonyms)
+   - Vague or overloaded terms
+3. **Propose a canonical glossary** with opinionated term choices
+4. **Write to `UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+5. **Output a summary** inline in the conversation
+
+## Output Format
+
+Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
+
+```md
+# Ubiquitous Language
+
+## Order lifecycle
+
+| Term        | Definition                                              | Aliases to avoid      |
+| ----------- | ------------------------------------------------------- | --------------------- |
+| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
+| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
+
+## People
+
+| Term         | Definition                                  | Aliases to avoid       |
+| ------------ | ------------------------------------------- | ---------------------- |
+| **Customer** | A person or organization that places orders | Client, buyer, account |
+| **User**     | An authentication identity in the system    | Login, account         |
+
+## Relationships
+
+- An **Invoice** belongs to exactly one **Customer**
+- An **Order** produces one or more **Invoices**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
+> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
+- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
+- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
+- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
+
+<example>
+
+## Example dialogue
+
+> **Dev:** "How do I test the **sync service** without Docker?"
+
+> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
+
+> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
+
+> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
+
+</example>
+
+## Re-running
+
+When invoked again in the same conversation:
+
+1. Read the existing `UBIQUITOUS_LANGUAGE.md`
+2. Incorporate any new terms from subsequent discussion
+3. Update definitions if understanding has evolved
+4. Re-flag any new ambiguities
+5. Rewrite the example dialogue to incorporate new terms

package/skills/use-my-browser/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: use-my-browser
+description: Use when work depends on the user's live browser session or visible rendered state rather than static fetches, especially for browser debugging contexts or DevTools-selected elements or requests, logged-in dashboards or CMS flows, localhost apps, forms, uploads, downloads, media inspection, DOM or iframe inspection, Shadow DOM, or browser failures that look like soft 404s, auth walls, anti-bot checks, or rate limits.
+---
+
+Do not treat this skill as a generic browsing default. Route from the evidence you need, not from tool preference.
+
+Every task must be classified before you choose a route:
+
+- `static-capable`: the evidence can be produced without live browser state, visible confirmation, or page interaction
+- `browser-required`: the evidence depends on rendered state, interaction, live session behavior, or browser-only structures
+
+Only `static-capable` tasks may fall back to static retrieval, `curl`, or other non-browser paths. Once a task is `browser-required`, stay on the browser path and mark missing capability as `blocked` instead of silently downgrading.
+
+## Prerequisite check
+
+This skill is for work inside the user's live browser session, not for launching a separate fresh automation browser.
+
+Before doing browser automation, confirm that your environment already has access to a live browser stack that can provide the capabilities the task depends on, such as page inventory, task-owned page creation, page selection, snapshots or visible-state reads, DOM inspection, text or form input, uploads, dialogs, console inspection, and network inspection. The exact stack does not matter here: confirm capability, not brand.
+
+If the live browser stack is unavailable, do not attempt browser automation through this skill. Only `static-capable` work may fall back to static retrieval.
+
+Live browser automation can trigger anti-bot or anti-automation defenses on some sites. Use browser interaction only when the task truly needs it, and avoid unnecessary repetitive actions once the needed evidence has been obtained.
+
+## Experience loop
+
+Treat site patterns as part of the browser protocol, not as optional background reading.
+
+For `browser-required` work, run this loop:
+
+1. As soon as the target domain is known, check whether a matching note already exists under [`references/site-patterns/`](./references/site-patterns/).
+2. If a note exists, read it before the first meaningful browser mutation on that domain.
+3. During the run, watch for verified site-specific facts that would change how a future run should operate.
+4. Before you consider the task complete, decide whether the run produced a reusable fact, disproved an existing fact, or produced no reusable site-specific learning.
+5. If the run verified something reusable or disproved an existing claim, update the matching note before finishing.
+
+Do not create a domain note for one-off noise. Do not skip the end-of-run review just because the task itself succeeded.
+
+Writeback is expected when a run verifies any of the following:
+
+- a stable route shape or required query parameter
+- a login, session inheritance, or `isolatedContext` quirk
+- a reliable interaction primitive such as hover, keyboard entry, upload sequencing, or a selector bridge pattern
+- a domain where DOM-generated links are reliable but hand-built URLs are not
+- predictable anti-automation friction or a misleading platform error state
+- a reusable media extraction or iframe / Shadow DOM access pattern
+
+## Decision guide
+
+Start with the outcome, not the tool. Make the user's goal explicit, define what counts as done, and choose the cheapest route that can still produce the right evidence.
+
+Use this routing order:
+
+1. Decide whether the task is `static-capable` or `browser-required`.
+2. If the task is `static-capable`, load [`references/task-routing.md`](./references/task-routing.md) and stay on the cheapest route that still satisfies the evidence target.
+3. If the task is `browser-required`, load [`references/browser-playbook.md`](./references/browser-playbook.md).
+4. If browser-required capability is uncertain in a fresh host session, also load [`references/browser-capability-matrix.md`](./references/browser-capability-matrix.md).
+5. If the user already has an active browser debugging context, such as a selected inspector element or network request, also load [`references/debug-handoff.md`](./references/debug-handoff.md).
+6. If the browser-required task touches a logged-in dashboard, admin surface, CMS, editor, or any save / publish / update flow, also load [`references/control-plane-workflows.md`](./references/control-plane-workflows.md).
+7. If the current failure shape suggests a soft 404, content-unavailable state, suspicious no-op interaction, auth wall, rate limit, or anti-automation defense, also load [`references/anti-automation-friction.md`](./references/anti-automation-friction.md).
+8. If the browser-required task includes iframe, Shadow DOM, collapsed content, or lazy-loaded evidence, also load [`references/deep-dom.md`](./references/deep-dom.md).
+9. If the important evidence lives in an image, audio clip, or video, also load [`references/media-inspection.md`](./references/media-inspection.md).
+10. If browser work can be divided across independent page owners or sub-agents, also load [`references/parallel-browser-ownership.md`](./references/parallel-browser-ownership.md).
+11. If you already know a reliable selector but need an MCP-native `uid` target, also load [`references/selector-bridge.md`](./references/selector-bridge.md).
+12. If page actions leave state ambiguous, a page unexpectedly navigates, an old `uid` may have gone stale, or console / network inspection is now needed to explain the next browser decision, also load [`references/browser-recovery.md`](./references/browser-recovery.md).
+13. If the target site already has a matching domain note under [`references/site-patterns/`](./references/site-patterns/), read that note before operating on the site.
+
+Treat the following as `browser-required` by default:
+
+- `localhost`, `127.0.0.1`, or benchmark-style local fixtures
+- uploads, downloads, drag-and-drop, hover, keyboard-native entry, or visible confirmation states
+- same-origin iframe inspection, Shadow DOM inspection, `details` / collapsed evidence, or lazy-loaded content
+- any task where "what the page visibly shows" is itself the evidence
+
+The normal happy path for a common task is this entrypoint plus one or two references, not the entire reference set.
+
+## Hard rules
+
+- Use browser interaction only when live browser state is part of the evidence or required action.
+- Once a task is `browser-required`, do not silently downgrade.
+- Treat this file as the entrypoint and each reference file as a single-purpose authority. Do not duplicate rules across files.
+- Keep reference loading one level deep. Decide the next file from this entrypoint instead of turning one reference into a hub that links to more references.
+- Do not ask the user to log in just because a page looks restricted. First confirm whether the target content or action is actually blocked.
+- Prefer site-generated DOM links over hand-built URLs once the page has shown you the path it expects.
+- Prefer MCP-native actions over script-driven interaction when the task is genuinely an in-browser action.
+- Only close pages you created.
+- Prefer primary sources over aggregators or repeated secondary reporting.
+- If a matching site pattern note exists, read it before the first meaningful browser mutation on that domain.
+- Do not finish a `browser-required` task without explicitly checking whether the run should create, update, downgrade, or remove a site-pattern claim.
+- If an existing site-pattern claim fails under comparable conditions, stop trusting it, fall back to the generic workflow, and update the note instead of retrying the stale assumption.
+- Do not use `curl`, `Invoke-WebRequest`, or shell HTTP fetches for `browser-required` tasks.
+- Do not treat a generic page-opening tool as evidence that localhost deep interaction is available.
+- Do not switch routes just because a browser capability probe failed. Record the missing capability and stop.
+- When the user indicates an active browser debugging context, prefer handoff from that current context over fresh reproduction from scratch.
+
+## Reference index
+
+- [`references/task-routing.md`](./references/task-routing.md): static retrieval vs live browser routing
+- [`references/browser-playbook.md`](./references/browser-playbook.md): core page-action protocol and base browser loop
+- [`references/browser-capability-matrix.md`](./references/browser-capability-matrix.md): capability proof for uncertain host sessions
+- [`references/debug-handoff.md`](./references/debug-handoff.md): active debugging-context handoff
+- [`references/control-plane-workflows.md`](./references/control-plane-workflows.md): logged-in dashboard / CMS save-publish discipline
+- [`references/anti-automation-friction.md`](./references/anti-automation-friction.md): soft 404 / auth / anti-automation classification
+- [`references/deep-dom.md`](./references/deep-dom.md): iframe, Shadow DOM, collapsed, or lazy-loaded evidence
+- [`references/media-inspection.md`](./references/media-inspection.md): image, audio, and video evidence
+- [`references/parallel-browser-ownership.md`](./references/parallel-browser-ownership.md): multi-owner browser coordination
+- [`references/selector-bridge.md`](./references/selector-bridge.md): selector-to-`uid` bridging
+- [`references/browser-recovery.md`](./references/browser-recovery.md): stale `uid`, navigation drift, and console / network escalation
+- [`references/site-patterns/README.md`](./references/site-patterns/README.md): site-pattern note maintenance rules
+- [site-patterns/{domain}.md](./references/site-patterns/): existing domain-specific operating knowledge

package/skills/using-superpowers/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## Instruction Priority
+
+Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
+
+1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
+2. **Superpowers skills** — override default system behavior where they conflict
+3. **Default system prompt** — lowest priority
+
+If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+
+## How to Access Skills
+
+**Never read skill files manually with file tools** — always use your platform's skill-loading mechanism so the skill is properly activated.
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly.
+
+**In Codex:** Skills load natively. Follow the instructions presented when a skill activates.
+
+**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins.
+
+**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+## Platform Adaptation
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "About to enter plan mode?" [shape=doublecircle];
+    "Already brainstormed?" [shape=diamond];
+    "Invoke brainstorming skill" [shape=box];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke the skill" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create a todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "About to enter plan mode?" -> "Already brainstormed?";
+    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+    "Invoke brainstorming skill" -> "Might any skill apply?";
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create a todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create a todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, systematic-debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → systematic-debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/skills/vector-database-setup/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: vector-database-setup
+description: Set up vector databases with indexing, similarity search, and hybrid retrieval
+category: AI Agents
+---
+
+# Vector Database Setup
+
+## Overview
+Set up vector databases with indexing, similarity search, and hybrid retrieval. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply vector database setup best practices
+- When establishing processes or standards for your workflow
+- When training team members on vector database setup
+- When automating or optimizing vector database setup tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply vector database setup for my current project
+Assistant: I'll help you apply vector database setup step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration