opencode-skills-collection 3.0.34 → 3.0.36

package/bundled-skills/social-metadata-hardening/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: social-metadata-hardening
-description: "Fix social sharing previews so URLs render as rich cards on Facebook, LinkedIn, X/Twitter, WhatsApp, Telegram, Slack, and Discord. Covers OG tags, Twitter cards, absolute image URLs, and metadata debugging."
+description: "Fix social sharing previews so URLs render as rich cards on Facebook, LinkedIn, X/Twitter, WhatsApp, Telegram, and more. Covers OG tags, Twitter cards, absolute image URLs, and debugging."
 category: seo
 risk: safe
 source: self
@@ -141,7 +141,7 @@ export const metadata = {
 };
 ```
 
-> ⚠️ **`metadataBase` is critical.** Without it, Next.js generates relative OG image URLs that every platform rejects.
+> ⚠️ **Set `metadataBase` when using relative metadata URLs.** If your helper already outputs absolute canonical/OG URLs, previews can still work without it.
 
 ---
 
@@ -198,6 +198,7 @@ curl -s https://www.yourdomain.com/blog/my-post | grep -i "og:\|twitter:"
 If tags don't appear → they're being added by JavaScript (not crawlable). Fix: move to `export const metadata` or `generateMetadata`.
 
 ### 2. Validate with platform tools
+
 | Platform | Tool |
 |----------|------|
 | Facebook | https://developers.facebook.com/tools/debug/ |
@@ -226,5 +227,5 @@ After deploying fixes, paste the URL into each platform's debugger and click "Fe
 ## Limitations
 
 - Cannot force immediate cache refresh on every social platform; some previews may remain stale after a correct fix.
-- Requires deployed, publicly reachable URLs for reliable validation with platform debuggers.
+- Requires publicly reachable deployed URLs for reliable validation with platform debuggers.
 - Does not replace brand, accessibility, or legal review of image text, alt text, and preview copy.

package/bundled-skills/social-post-writer-seo/SKILL.md

@@ -93,6 +93,25 @@ Check the link in bio to pre-order!
 - ❌ Avoid using more than 10 hashtags; it can look like spam.
 - ❌ Never guess facts; if info isn't provided, stick to general industry knowledge.
 
+## Examples
+
+### Example: New Product Launch
+- **Topic**: Solar Powered Coffee Mug
+- **Keyword**: eco-friendly coffee
+- **Target**: Commuters
+- **Platform**: Instagram
+- **Tone**: Insightful
+
+**Output**:
+☕️ Your morning coffee just got a clean energy upgrade! 
+Your commute just got smarter and greener. 
+The SolMug keeps your brew hot using only sunlight. 
+A small change for your bag, a big win for the planet. 
+Check the link in bio to pre-order! 
+#ecofriendly #coffee #sustainability #tech #morningroutine
+
+---
+
 ## Limitations
 - This skill does not generate image or video assets.
 - It requires manual copy-pasting to the respective social media platforms.

package/bundled-skills/tdd-workflows/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: tdd-workflows
+description: "Use when working with tdd workflows tdd cycle (Alias for tdd-workflows-tdd-cycle)"
+risk: unknown
+source: "alias"
+date_added: "2026-06-02"
+---
+
+# Tdd Workflows
+
+> **This is an alias.** The canonical skill is **`tdd-workflows-tdd-cycle`**.
+
+This skill redirects to `tdd-workflows-tdd-cycle`. Load it from the vault:
+
+`skill-libraries/testing/tdd-workflows-tdd-cycle/SKILL.md`
+
+## When to Use
+- Use this skill when working with tdd workflows tdd cycle (Alias for tdd-workflows-tdd-cycle)
+
+## Why this alias exists
+
+Users commonly search for `tdd-workflows` but the full skill name in this collection is `tdd-workflows-tdd-cycle`. This alias ensures discoverability.
+
+## 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.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+## Examples
+```text
+Use @tdd-workflows for this task: Use when working with tdd workflows tdd cycle (Alias for tdd-workflows-tdd-cycle).
+
+Apply the skill to my current work and walk me through the safest next steps,
+key checks, and the concrete output I should produce.
+```

package/bundled-skills/user-thoughts/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: user-thoughts
+description: >-
+  Persist user decisions and project constraints to mdbase across sessions.
+  Trigger on /user-thoughts or /ustht, or when the user discusses architecture,
+  tech stack, rules, UI/UX, or project memory.
+license: MIT
+source: "https://github.com/JularDepick/user-thoughts.SKILL"
+source_repo: JularDepick/user-thoughts.SKILL
+source_type: community
+date_added: "2026-05-31"
+author: JularDepick
+tags: [userthoughts, documentation, project-management, mdbase]
+tools: [claude, cursor, gemini]
+risk: safe
+allowed-tools: read write bash
+metadata:
+  author: JularDepick
+  category: productivity
+  supported_agents: "[claude, cursor, gemini]"
+---
+
+# user-thoughts.SKILL
+
+## Overview
+
+Across sessions and across agents, project decisions and user constraints are easy to lose. `user-thoughts` persists those decisions into a project-local `mdbase` so any future agent can recover the user's intent without re-deriving it from scratch.
+
+The skill records user intent. It does not replace normal task execution. If the user says, "make the button red," the agent should both make the change and record the preference when persistent project memory is useful.
+
+## When to Use
+
+Use this skill when the user states or revises:
+
+- Project rules, constraints, preferences, or requirements.
+- Architecture, tech-stack, data-model, deployment, or workflow decisions.
+- UI/UX direction, copy standards, visual preferences, or design rationale.
+- Backlog items, planned work, rejected options, or decisions that future agents should inherit.
+- A direct command beginning with `/user-thoughts` or `/ustht`.
+
+Do not use it for unrelated small talk, transient chatter, or content the user explicitly asks to ignore.
+
+## Language Policy
+
+- All bundled skill files, scripts, templates, and reference docs are written in English.
+- Agent-facing command output should follow the user's current conversation language when the agent can reasonably do so.
+- Raw user thoughts should preserve the user's original wording. Do not translate, summarize, or clean the user's intent unless the user asks for that.
+
+## Core Workflow
+
+```text
+User message -> Agent identifies persistent project intent -> write to #raw/
+             -> /ustht sortin groups raw entries into #mdbase/
+             -> /ustht mdbase show exposes the organized memory base
+```
+
+## Runtime Modes
+
+- Passive mode: `INSTANT_STATUS=off`; only explicit skill commands run.
+- Instant mode: `INSTANT_STATUS=on` and `SKILL_STATUS=on`; project-relevant user thoughts are written to `#raw/` as they appear.
+- Ignore mode: `ignore start` and `ignore end` mark a temporary interval that should not be recorded.
+- Read-only mode: if required read/write/bash tools are unavailable, show commands can still work but write commands should explain that the environment cannot persist data.
+
+`SKILL_STATUS=off` pauses instant capture even when `INSTANT_STATUS=on`. Ignore intervals are context-local and do not persist across sessions.
+
+## Path Definitions
+
+- `@/`: the installed `user-thoughts/` skill directory.
+- `~/`: the current project working directory.
+- `#ustht/`: `~/.ustht/`.
+- `#mdbase/`: `~/.ustht/mdbase/`.
+- `#ignored/`: `~/.ustht/ignored/`.
+- `#raw/`: `~/.ustht/raw/`.
+- `#export/`: `~/.ustht/export/`.
+
+## Runtime Directory Layout
+
+```text
+.ustht/
+├── define.ini
+├── README.ai.md
+├── raw/
+│   └── yyyy-mm-dd.md
+├── ignored/
+│   └── yyyy-mm-dd.md
+├── mdbase/
+│   ├── backlog.md
+│   ├── README.ai.md
+│   └── details/
+│       ├── rules.md
+│       ├── plans.md
+│       ├── ui/
+│       │   ├── outline.md
+│       │   └── details.md
+│       ├── dev-stack.md
+│       └── general.md
+└── export/
+```
+
+## Tools and Environment
+
+Required tools:
+
+- read/write: read and update files under `#ustht/`.
+- bash: create directories and run bundled scripts.
+
+Optional tool:
+
+- SubAgent: when available, use it for semantic `sortin` or `resort` maintenance that spans many files. Use the main agent directly only when subagents are unavailable.
+
+## Bundled Scripts
+
+The `scripts/` directory provides small Python helpers for mechanical operations:
+
+| Script | Purpose | Example |
+|---|---|---|
+| `common.py` | Shared helpers | Imported by other scripts |
+| `status.py` | Show current runtime state | `python @/scripts/status.py` |
+| `init.py` | Initialize `.ustht/` | `python @/scripts/init.py` |
+| `show_raw.py` | Show unprocessed raw entries | `python @/scripts/show_raw.py` |
+| `show_mdbase.py` | Show mdbase index or a dimension | `python @/scripts/show_mdbase.py show --all` |
+| `sortin.py` | Soft-maintain raw entries into mdbase | `python @/scripts/sortin.py --dry` |
+| `write_raw.py` | Append one raw thought | `python @/scripts/write_raw.py "Use REST APIs" --dim dev-stack` |
+| `toggle.py` | Toggle skill or instant mode | `python @/scripts/toggle.py instant on` |
+| `ignore_ops.py` | Manage ignored entries | `python @/scripts/ignore_ops.py show` |
+
+`resort` has no standalone script because it requires semantic review, deduplication, and restructuring by an agent.
+
+## define.ini
+
+`define.ini` stores simple key/value runtime state:
+
+| Key | Value | Meaning |
+|---|---|---|
+| `SKILL_STATUS` | `on` or `off` | Whether the skill accepts write operations |
+| `INSTANT_STATUS` | `on` or `off` | Whether instant capture is enabled |
+| `LAST_SORTIN` | `yyyy-mm-dd HH:MM` or empty | Last soft-maintenance time |
+
+Write the file atomically by replacing its complete contents. Do not append partial key/value fragments.
+
+## Commands
+
+Commands may use either `/user-thoughts` or `/ustht`.
+
+### Status and Toggles
+
+- `/ustht init`: create `.ustht/` and copy templates.
+- `/ustht status`: show status, raw counts, and dimension counts.
+- `/ustht skill`: show skill status.
+- `/ustht skill on|off`: enable or disable writes.
+- `/ustht instant`: show instant-capture status.
+- `/ustht instant on|off`: enable or disable instant capture.
+
+### Maintenance
+
+- `/ustht sortin [--dry]`: append unprocessed raw entries into mdbase.
+- `/ustht resort [--dry]`: semantically review and reorganize all mdbase content.
+
+### Ignore Management
+
+- `/ustht ignore start|end`: start or end an ignore interval.
+- `/ustht ignore --last`: remove the last raw entry and record it in `#ignored/`.
+- `/ustht ignore`: same as `--last` when used as a standalone command.
+- `/ustht ignore show`: list ignored entries.
+- Any message ending in `/ustht ignore` or `/user-thoughts ignore`: ignore that message.
+
+### Content Review and Export
+
+- `/ustht raw`: show unprocessed raw entries.
+- `/ustht mdbase show [--all|--dimension]`: show the index, all dimensions, or one dimension.
+- `/ustht mdbase export [--all|--dimension]`: export mdbase content to `#export/`.
+- `/ustht import <path>`: scan markdown files under a safe project-local path and merge project-relevant decisions into mdbase.
+
+Chain commands with `&&`, for example `/ustht skill on && instant on`.
+
+## Instant Capture
+
+When instant mode is active:
+
+1. Decide whether the user message contains project-relevant intent.
+2. Write one raw line per independent thought using `- [HH:MM] original text | suggested-dim:dimension`.
+3. Do not update mdbase directly; wait for `sortin`.
+4. Skip ignored messages and ignore intervals.
+5. Keep normal user work moving. Recording should not block task execution.
+6. If one day accumulates more than five raw entries, suggest `/ustht sortin`.
+
+## Sortin and Resort
+
+`sortin` is soft maintenance:
+
+1. Read unprocessed `#raw/*.md` files.
+2. Parse entries and their suggested dimensions.
+3. Append them to matching `#mdbase/` files grouped by date.
+4. Mark processed raw files with `<!-- processed -->` on the first line.
+5. Update `LAST_SORTIN` and the mdbase index.
+
+`resort` is hard maintenance:
+
+1. Review all mdbase files.
+2. Deduplicate overlapping records.
+3. Move entries into better dimensions when justified by the user's own wording.
+4. Mark deprecated dimensions instead of deleting them unless the user explicitly requests deletion.
+5. Preserve provenance and user wording.
+
+## Best Practices
+
+- Record explicit user decisions faithfully.
+- Do not over-infer. Store only what the user said or what follows directly from it.
+- Preserve original wording, including negations, numbers, links, constraints, and tradeoffs.
+- Split one message into multiple records when it contains independent decisions.
+- Resolve conflicts by treating the newest user statement as current while preserving the older record as historical context.
+- Put unmatched project-relevant items in `general.md` instead of inventing too many dimensions.
+- Do not record unrelated conversation.
+
+## Limitations
+
+- The skill records intent; it does not validate whether the user's idea is correct, feasible, secure, or internally consistent.
+- Dimension assignment depends on agent judgment and may need user correction through `resort`.
+- Ignore intervals are context-local and do not persist across sessions.
+- `.ustht/` can contain sensitive information. The skill does not redact content; users must use ignore commands or repository hygiene to manage sensitive data.
+- The workflow is not file-lock based. In multi-agent environments, agents must coordinate to avoid conflicting writes.
+
+## Safety Rules
+
+- Keep all runtime writes inside `#ustht/`.
+- Validate dimension names: lowercase letters, digits, hyphens, and `/` subdirectories only; no `..`, backslashes, spaces, absolute paths, or reserved names.
+- Do not execute user-provided shell commands.
+- Do not recursively copy directories with shell commands during initialization; copy known template files safely.
+- Treat `<!-- processed -->` as meaningful only when it is the first line of a raw file.
+- Never silently delete dimension files; mark deprecated content unless the user explicitly asks for deletion.
+
+More detail is available in `references/safety.md`, `references/sortin.md`, `references/commands.md`, and `references/edge-cases.md`.
+
+## Related Skills
+
+None. This skill is intentionally focused on project-local user intent persistence.

package/bundled-skills/user-thoughts/assets/Runtime-Template/README.ai.md

@@ -0,0 +1,13 @@
+# user-thoughts Runtime Directory
+
+This directory stores project-local user intent captured by `user-thoughts`.
+
+## Contents
+
+- `define.ini`: runtime state for the skill.
+- `raw/`: unprocessed user thoughts captured by date.
+- `ignored/`: entries the user explicitly chose not to record.
+- `mdbase/`: organized project memory grouped by dimension.
+- `export/`: exported mdbase content.
+
+Do not delete this directory unless the user explicitly wants to discard project memory.

package/bundled-skills/user-thoughts/assets/Runtime-Template/define.ini

@@ -0,0 +1,3 @@
+SKILL_STATUS=on
+INSTANT_STATUS=off
+LAST_SORTIN=

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/README.ai.md

@@ -0,0 +1,25 @@
+# user-thoughts mdbase Index
+
+This directory stores user-provided project decisions, constraints, preferences, and plans. Keep the user's original intent intact.
+
+Last updated: never
+
+## Maintenance Rules
+
+- Preserve details from user wording. Do not simplify away constraints, numbers, negations, or examples.
+- Classify entries by dimension so future agents can find them quickly.
+- Prefer existing dimensions. Create a new dimension only when the user's thought clearly needs one.
+- Append new records by date under `## yyyy-mm-dd` headings.
+- Do not delete historical content unless the user explicitly asks for deletion.
+
+## Document Index
+
+| File | Dimension | Entries |
+|------|-----------|---------|
+| [backlog.md](backlog.md) | backlog | 0 |
+| [details/rules.md](details/rules.md) | rules | 0 |
+| [details/plans.md](details/plans.md) | plans | 0 |
+| [details/dev-stack.md](details/dev-stack.md) | dev-stack | 0 |
+| [details/ui/outline.md](details/ui/outline.md) | ui/outline | 0 |
+| [details/ui/details.md](details/ui/details.md) | ui/details | 0 |
+| [details/general.md](details/general.md) | general | 0 |

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/backlog.md

@@ -0,0 +1,19 @@
+# Backlog
+
+> User plans, pending tasks, and work that has been requested but not started.
+
+## Pending
+
+<!-- Items explicitly requested by the user but not started yet. -->
+
+## In Progress
+
+<!-- Items that have started but are not complete. -->
+
+## Done
+
+<!-- Completed items retained for traceability. -->
+
+## Notes
+
+Record the date each item was raised. When an item is completed, move it to Done and include the completion date when known.

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/dev-stack.md

@@ -0,0 +1,7 @@
+# Development Stack Decisions
+
+> Frameworks, libraries, services, deployment choices, data stores, APIs, and other technical stack decisions.
+
+## Current Decisions
+
+<!-- Append dated user decisions here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/general.md

@@ -0,0 +1,7 @@
+# General Project Notes
+
+> Project-relevant thoughts that do not fit another dimension yet.
+
+## Current Notes
+
+<!-- Append dated user thoughts here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/plans.md

@@ -0,0 +1,7 @@
+# Project Plans
+
+> Directional plans, milestones, priorities, sequencing, and strategic project ideas.
+
+## Current Plans
+
+<!-- Append dated user plans here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/rules.md

@@ -0,0 +1,7 @@
+# Project Rules and Constraints
+
+> User-defined rules, constraints, conventions, preferences, and non-negotiables.
+
+## Current Rules
+
+<!-- Append dated user rules here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/ui/details.md

@@ -0,0 +1,7 @@
+# UI Details
+
+> Component-level UI preferences, interaction details, copy details, spacing, states, and visual refinements.
+
+## Current Details
+
+<!-- Append dated UI detail decisions here. -->

package/bundled-skills/user-thoughts/assets/Runtime-Template/mdbase/details/ui/outline.md

@@ -0,0 +1,7 @@
+# UI Outline
+
+> Product-level UI direction, layout concepts, design principles, themes, and screen-level decisions.
+
+## Current Direction
+
+<!-- Append dated UI outline decisions here. -->

package/bundled-skills/user-thoughts/references/commands.md

@@ -0,0 +1,54 @@
+# Command Reference
+
+`user-thoughts` accepts `/user-thoughts` and `/ustht`. They are equivalent.
+
+## Command Summary
+
+| Command | Meaning |
+|---|---|
+| `/ustht init` | Initialize `.ustht/` in the current project. |
+| `/ustht status` | Show skill state, instant state, raw count, and dimension count. |
+| `/ustht skill` | Show `SKILL_STATUS`. |
+| `/ustht skill on|off` | Enable or disable write operations. |
+| `/ustht instant` | Show `INSTANT_STATUS`. |
+| `/ustht instant on|off` | Enable or disable instant capture. |
+| `/ustht sortin [--dry]` | Append raw entries into mdbase. |
+| `/ustht resort [--dry]` | Reorganize all mdbase content semantically. |
+| `/ustht raw` | Show unprocessed raw entries. |
+| `/ustht mdbase show [--all|--dimension]` | Show the index, all dimensions, or one dimension. |
+| `/ustht mdbase export [--all|--dimension]` | Export mdbase content. |
+| `/ustht import <path>` | Import project-relevant decisions from markdown files. |
+| `/ustht ignore start|end` | Start or stop a temporary ignore interval. |
+| `/ustht ignore --last` | Remove the last raw entry and record it as ignored. |
+| `/ustht ignore show` | Show ignored entries. |
+
+## Natural-Language Mapping
+
+Agents may map clear user intent to commands:
+
+- "turn on project memory" -> `/ustht skill on && instant on`
+- "stop recording this" -> `/ustht ignore start`
+- "start recording again" -> `/ustht ignore end`
+- "organize what I said" -> `/ustht sortin`
+- "show what you remember" -> `/ustht mdbase show`
+- "ignore the last note" -> `/ustht ignore --last`
+
+When intent is ambiguous, ask a short clarification instead of guessing.
+
+## Chained Commands
+
+Commands can be chained with `&&` and should run left to right. Stop only if a command fails in a way that makes the following command unsafe.
+
+Example:
+
+```text
+/ustht skill on && instant on && status
+```
+
+## Dimension Arguments
+
+Dimension names must pass validation:
+
+- lowercase letters, digits, and hyphens;
+- `/` allowed for subdirectories, such as `ui/outline`;
+- no spaces, `..`, backslashes, absolute paths, or reserved names.

package/bundled-skills/user-thoughts/references/edge-cases.md

@@ -0,0 +1,84 @@
+# Edge Cases
+
+Use these examples to keep behavior predictable.
+
+## No Runtime Directory
+
+User: `/ustht status`
+
+Agent: `.ustht/ was not found. Run /ustht init first.`
+
+## Skill Disabled
+
+If `SKILL_STATUS=off`, write commands should not modify files. Read commands such as `status`, `raw`, and `mdbase show` may still run.
+
+## Instant Mode Disabled
+
+When `INSTANT_STATUS=off`, do not capture natural-language thoughts automatically. Explicit commands still run.
+
+## Command Plus Thought
+
+User: `Make buttons use 8px radius, and /ustht status`
+
+Agent: run the command and record the UI preference if instant capture is enabled. Do not record the command text itself.
+
+## Message Suffix Ignore
+
+User: `This color experiment is temporary /ustht ignore`
+
+Agent: do not write it to raw. Record it in `ignored/` as a suffix-ignored entry if ignore tracking is available.
+
+## Ignore Interval
+
+User: `/ustht ignore start`
+
+Agent: enter ignore mode for the current context.
+
+User: `Try three throwaway layouts.`
+
+Agent: do not record the thought.
+
+User: `/ustht ignore end`
+
+Agent: exit ignore mode.
+
+## Last Entry Ignore
+
+User: `/ustht ignore --last`
+
+Agent: remove the last unprocessed raw entry and append it to `ignored/`. If no entry exists, say so without failing.
+
+## Processed Marker Mentioned by User
+
+User: `Maybe we should use <!-- processed --> as a completion marker in docs.`
+
+Agent: preserve that text as ordinary user content. `sortin` checks only the first line of raw files.
+
+## Illegal Dimension Names
+
+Reject dimensions containing spaces, `..`, backslashes, absolute paths, or unsafe characters.
+
+Examples:
+
+- Reject `../../../etc/passwd`.
+- Reject `my file`.
+- Accept `ui/details`.
+- Accept `dev-stack`.
+
+## Chained Commands
+
+User: `/ustht skill on && instant on && status`
+
+Agent: run commands left to right and report a compact summary.
+
+## Import With No Relevant Content
+
+If `/ustht import README.md` finds no project decisions, report that no entries were extracted and do not write empty dimension sections.
+
+## Multi-Agent Writes
+
+No file locks are provided. If multiple agents are active, coordinate before `sortin` or `resort` to avoid conflicting writes.
+
+## Sensitive Content
+
+If the user says a thought contains secrets or personal data, prefer ignore behavior and remind them that `.ustht/` is not automatically redacted.

package/bundled-skills/user-thoughts/references/safety.md

@@ -0,0 +1,65 @@
+# Safety and Data Integrity
+
+This document defines path safety, input validation, and data-integrity rules for `user-thoughts`.
+
+## Path Safety
+
+All runtime file operations must stay inside `#ustht/` unless an import command reads project-local markdown files.
+
+Dimension names are used to construct paths, so validate them strictly:
+
+| Rule | Reason |
+|---|---|
+| Each path segment uses `[a-z0-9-]` only | Prevents shell and path surprises. |
+| Each segment starts and ends with `[a-z0-9]` | Avoids hidden or malformed files. |
+| `/` is allowed only as a dimension subdirectory separator | Supports `ui/outline`. |
+| `..`, backslashes, spaces, and absolute paths are forbidden | Prevents path traversal. |
+| Reserved names are forbidden | Avoids collisions with runtime folders. |
+
+Reserved names: `backlog`, `readme-ai`, `export`, `raw`, `ignored`, `define`, `general`.
+
+## Content Safety
+
+Raw entries use this format:
+
+```text
+- [HH:MM] original user text | suggested-dim:dimension
+```
+
+The suffix is agent-generated metadata. User text may contain markdown and should be preserved as written. Parse the last ` | suggested-dim:` separator only.
+
+`<!-- processed -->` is meaningful only as the first line of a raw file. If the user mentions that string inside a thought, treat it as normal content.
+
+## define.ini Safety
+
+Allowed keys and values:
+
+| Key | Allowed value |
+|---|---|
+| `SKILL_STATUS` | `on` or `off` |
+| `INSTANT_STATUS` | `on` or `off` |
+| `LAST_SORTIN` | empty or `yyyy-mm-dd HH:MM` |
+
+Values must not contain newlines or `=`. Write the whole file rather than appending partial fragments.
+
+## Shell Safety
+
+- Do not execute user-provided shell commands.
+- Do not use `eval` or dynamic execution.
+- Construct file paths only from validated dimensions or fixed template paths.
+- During initialization, copy known template files safely instead of recursively shell-copying arbitrary directories.
+
+## Data Integrity
+
+`sortin` is not fully atomic. To reduce partial-write risk:
+
+1. Parse raw entries first.
+2. Write dimension files.
+3. Mark raw files as processed only after writes succeed.
+4. Update `LAST_SORTIN` last.
+
+Processed raw files are retained for traceability. Dimension files should be appended or marked deprecated; do not silently delete user history.
+
+## Sensitive Data
+
+The skill preserves original wording and does not redact secrets or personal data. Users should use ignore commands before sensitive content is captured, and teams should protect `.ustht/` with normal repository and filesystem hygiene.