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

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

.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:

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:

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