Define the skill entity for generation and curation

AGENTS.md

@@ -3,4 +3,4 @@
 - Keep runtime code in `src/index.ts` small. OpenCode loads that TypeScript source directly (no build). Reuse native skill discovery and file tools. Do not add a consent parser, write interceptor, persistence, background work, or a separate memory store.
 - Use V1 `experimental.chat.system.transform` and `experimental.session.compacting` only. 1.18.30’s V2 Promise `agent.transform` does not affect the normal session agent. Transform has no agent id: skip title/summary/compaction/explore by matching the built-in prefixes in `output.system` (recheck on OpenCode upgrades). Never set compacting `output.prompt`; skip the note if `prompt` is already set. Options are only `enabled` and `ignoredTopics`; unknown keys must throw. Inspect pinned `@opencode-ai/plugin` 1.18.30 types before changing hooks. Details: `docs/research.md`.
 - Node 24+. `npm run check` then `npm test` (`node --test test/*.test.ts`). That suite does not prove model compliance. Guidance or model-behavior changes: `test/SCENARIOS.md`. Isolated CLI from the checkout root (Docker + host `opencode` binary): `EVAL_SCRIPT=context sh test/live.sh` or `sh test/live.sh` (`EVAL_CASE=4` for one case). Never run evaluation writes against a real skill library.
-- Product skills go in `skills/` (opt-in `skills.paths`); keep `examples/` outside auto-discovery. Bundled skill `description` must start with `Use ONLY when `. Keep examples credential-free.
+- Product skills go in `skills/` (opt-in `skills.paths`); keep `examples/` outside auto-discovery. Bundled skill `description` must start with `Use ONLY when `. Generated descriptions are what+when, never that gate. Keep examples credential-free. Entity: `docs/skill-definition.md`.

README.md

@@ -5,7 +5,7 @@
 
 **Agent notices. Human decides. OpenCode remembers.**
 
-An [OpenCode](https://opencode.ai) [plugin](https://opencode.ai/docs/plugins/) that notices durable, reusable procedures during normal work and asks before saving them as native [skills](https://opencode.ai/docs/skills/).
+An [OpenCode](https://opencode.ai) [plugin](https://opencode.ai/docs/plugins/) that notices durable, reusable procedures during normal work and asks before saving them as native [skills](https://opencode.ai/docs/skills/). A skill is one on-demand job, not always-on project rules, an agent, a command, or memory.
 
 It is not a memory store, skill database, or write sandbox. After you approve, saves use OpenCode’s existing file tools and [permissions](https://opencode.ai/docs/permissions/).
 
@@ -91,7 +91,7 @@ The runtime is one file: it appends guidance and a compaction note. No extra mod
 | [`skills/`](skills/) | Opt-in mining and curation skills |
 | [`examples/`](examples/) | Sample generated skill (not auto-discovered) |
 | [`test/`](test/) | Hook tests and isolated live eval |
-| [`docs/`](docs/installation.md) | Install, troubleshooting, hook research |
+| [`docs/`](docs/installation.md) | Install, troubleshooting, hook research, [skill entity](docs/skill-definition.md) |
 
 ## Contributing
 

docs/research.md

@@ -2,7 +2,8 @@
 
 Maintainer notes for hook and runtime changes. Users installing the plugin can
 skip this file; see the [README](../README.md) and
-[installation](installation.md) instead.
+[installation](installation.md) instead. Skill generation and curation ontology:
+[skill-definition.md](skill-definition.md).
 
 ## Inspected before implementation
 

docs/skill-definition.md

@@ -0,0 +1,34 @@
+# Skill entity
+
+Maintainer notes for generation and curation. Install users can skip this;
+runtime hooks stay in [research.md](research.md).
+
+A **skill** is one on-demand job: a named folder whose `description` is the only
+discovery index, and whose body is the confirmed procedure the agent would get
+wrong without it.
+
+It is not always-on rules (`AGENTS.md`), an agent persona, a `/command`, or
+memory. Stay silent on those; do not write them.
+
+## Must hold
+
+Procedural, on-demand, discoverable (what + when + trigger terms), non-generic,
+confirmed, durable, one trigger family, secret-free.
+
+One job per skill. Split unrelated jobs. Merge if two skills would fire on the
+same future prompts and teach the same job. Prefer updating an existing skill.
+
+## Generated `SKILL.md`
+
+- Frontmatter: only native `name` and `description`. Folder matches `name`.
+- Description: third person, what it does and when to load it, distinct from
+  other known skills, 1–1024 characters. Never `Use ONLY when` (that gate is
+  for bundled `skill-mining` / `skill-curation`).
+- Body: confirmed steps, constraints, and verification only. Default with an
+  escape hatch, not a menu. No inferred rules, rollout counts, generic teaching,
+  transcripts, or today's outcome.
+- Supporting files only when the confirmed procedure actually needs them.
+
+Projections: always-on guidance in `src/index.ts`; explicit capture in
+`skills/skill-mining`; library hygiene in `skills/skill-curation`; shape in
+`examples/terraform-plan-review`.

examples/terraform-plan-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: terraform-plan-review
-description: Use when preparing Terraform changes for this team's environments; follow the team's saved-plan review and approval procedure.
+description: Review and apply this team's Terraform changes using the saved-plan procedure. Use when preparing, reviewing, or applying Terraform plans for this team's environments.
 ---
 
 # Terraform plan review

skills/skill-curation/SKILL.md

@@ -13,7 +13,15 @@ Discover skills OpenCode already knows (native `skill` listing and `SKILL.md` un
 
 Skip bundled OpenSkillGen skills (`skill-mining`, `skill-curation`) and built-ins such as `customize-opencode` unless the user named them. Do not invent skills that are not on disk.
 
-Look for: significant overlap, contradictions, obsolete instructions, unnecessary fragmentation, a clearly better replacement, empty/broken frontmatter, or secrets that should never have been stored.
+Judge each skill as one on-demand job whose description is the discovery index and whose body is the procedure the agent would get wrong without it.
+
+Look for:
+
+- Description missing what or when, first person, too broad/narrow, or colliding trigger terms with another skill
+- Body mixing two jobs (split) or two skills teaching the same job (merge)
+- Always-on conventions stored as a skill (propose delete; do not write AGENTS.md)
+- Generic model knowledge, inferred/unconfirmed rules, evidence or motivation in the body, equal-option menus, vague names (`helper`, `utils`)
+- Significant overlap, contradictions, obsolete instructions, unnecessary fragmentation, a clearly better replacement, empty/broken frontmatter, or secrets that should never have been stored
 
 When uncertain, leave the skill alone.
 
@@ -27,4 +35,4 @@ If nothing needs changing, say so and stop. Do not generate new procedural skill
 
 Do not write, merge, rename, or delete until the user approves that specific operation. Reviewing the library, listing overlap, or silence is not approval. Merging into a target does not authorize deleting the source unless the user said to delete it.
 
-After approval, use native file tools. Read before edit. Preserve unrelated sections and supporting files. Keep valid `name`/`description` frontmatter; folder name must match. Never persist secrets; strip them if that is the approved edit. Show each path changed. Restart OpenCode to refresh discovery.
+After approval, use native file tools. Read before edit. Preserve unrelated sections and supporting files. Keep valid `name`/`description` frontmatter; folder name must match. Generated descriptions stay third person, what+when+triggers, never "Use ONLY when". Never persist secrets; strip them if that is the approved edit. Show each path changed. Restart OpenCode to refresh discovery.

skills/skill-mining/SKILL.md

@@ -7,13 +7,23 @@ description: Use ONLY when the user explicitly asks to mine, extract, capture, o
 
 The user asked to mine skills. That is initiative to **propose** captures from this work, not a write permission and not a cue to suggest mining later on its own.
 
+## Entity
+
+A skill is one on-demand job: a named folder whose description is the only discovery index, and whose body is the confirmed procedure the agent would get wrong without it.
+
+Keep a candidate only if it is procedural, on-demand (not every session), discoverable (you can write a precise what+when description), non-generic, confirmed, durable, one trigger family, and secret-free.
+
+Drop as not-a-skill: always-on project conventions (AGENTS.md/rules), personas (agents), user-invoked prompts (commands), facts/memory, preferences, one-offs, speculation, this session's outcome, generic model knowledge. Stay silent; do not write AGENTS.md, agents, or commands.
+
+If two unrelated jobs appear, propose two skills. If you cannot write a what+when description without colliding with an existing skill, it is not a separate entity: update or drop.
+
 ## Mine
 
-From this conversation, extract only durable, reusable, specific knowledge the user would otherwise explain again: repeated workflows, consequential corrections, local conventions, proven troubleshooting, decision rules.
+From this conversation, extract only durable, reusable, specific knowledge the user would otherwise explain again: repeated workflows, consequential corrections, or proven troubleshooting.
 
 Skip temporary state, one-off commands, repository-obvious facts, generic knowledge, speculation, secrets, credentials, and casual preferences. When uncertain, omit the candidate.
 
-Load relevant existing skills first. Classify each candidate as new, improvement, duplicate, conflict, or temporary. Drop duplicates and temporary knowledge. Prefer updating an existing skill over creating another.
+Load relevant existing skills first. Classify each candidate as new, improvement, duplicate, conflict, not-a-skill, or temporary. Drop duplicates, not-a-skill, and temporary knowledge. Prefer updating an existing skill over creating another.
 
 ## Propose
 
@@ -25,4 +35,4 @@ Infer project scope for repository/team procedures; global only for how this use
 
 Do not write until the user approves the specific create/update (yes, rename, make it global, add X, merge with Y). Mining, silence, or task success is not approval. Merging does not authorize deleting a source skill unless that was explicit.
 
-After approval, use native file tools. Project: `.opencode/skills/<name>/SKILL.md`. Global: `~/.config/opencode/skills/<name>/SKILL.md`. Frontmatter `name` must match the folder (`^[a-z0-9]+(-[a-z0-9]+)*$`, ≤64). Description 1–1024 characters, when to use it. Body: confirmed rules, constraints, verification only — no transcripts, rollout counts, or today's outcome. Never persist secrets. Show the path. Restart OpenCode to rediscover it.
+After approval, use native file tools. Project: `.opencode/skills/<name>/SKILL.md`. Global: `~/.config/opencode/skills/<name>/SKILL.md`. Frontmatter `name` must match the folder (`^[a-z0-9]+(-[a-z0-9]+)*$`, ≤64). Description 1–1024 characters, third person, what it does + when to load it + trigger terms; distinct from other known skills; never "Use ONLY when". Body: confirmed rules, constraints, verification only — no transcripts, rollout counts, inferred steps, generic teaching, or today's outcome. Default with an escape hatch, not a menu. Never persist secrets. Show the path. Restart OpenCode to rediscover it.

src/index.ts

@@ -16,15 +16,17 @@ Explicit approval is mandatory BEFORE any skill write. A user describing a reusa
 
 Apply this only during normal user-facing work, never title generation, summarization, compaction, or delegated subagent tasks. Preserve pending proposals, explicit decisions, and rejected topics when summarizing; if approval is unclear after compaction, ask rather than infer it.
 
-Prioritize the user's actual task. Only at a natural stopping point, briefly suggest saving exceptionally useful, confirmed, durable knowledge the user would otherwise explain again: repeated workflows, consequential corrections, local conventions, or proven multi-step troubleshooting. When uncertain, stay silent. Ignore ordinary conversation, casual preferences, one-off commands, temporary state, repository-obvious facts, generic knowledge, speculation, and transient environment values. Separate confirmed rules from surrounding task status; never generalize today's outcome. Never force a suggestion per session; do not repeat rejected or ignored suggestions.
+A skill is one on-demand job: a named folder whose description is the only discovery index, and whose body is the confirmed procedure the agent would get wrong without it. Stay silent for always-on project conventions (AGENTS.md/rules), personas (agents), user-invoked prompts (commands), facts/memory, generic model knowledge, preferences, one-offs, speculation, and this session's outcome. Do not write AGENTS.md, agents, or commands.
 
-Before suggesting, consider OpenCode's available skills; load only relevant ones using the native skill tool. Distinguish new knowledge, improvement, duplicate, conflict, and temporary knowledge. Skip duplicates and temporary knowledge; prefer updating a relevant skill. When encountered during work, substantial overlap, contradictions, obsolete instructions, fragmentation, or a better replacement may justify proposing review/consolidation. Do not scan the library for cleanup or silently resolve conflicts.
+Prioritize the user's actual task. Only at a natural stopping point, briefly suggest saving exceptionally useful, confirmed, durable on-demand knowledge the user would otherwise explain again: repeated workflows, consequential corrections, or proven multi-step troubleshooting. When uncertain, stay silent. Ignore ordinary conversation, casual preferences, one-off commands, temporary state, repository-obvious facts, generic knowledge, speculation, and transient environment values. Separate confirmed rules from surrounding task status; never generalize today's outcome. Never force a suggestion per session; do not repeat rejected or ignored suggestions.
+
+Before suggesting, consider OpenCode's available skills; load only relevant ones using the native skill tool. Distinguish new knowledge, improvement, duplicate, conflict, and temporary knowledge. Skip duplicates and temporary knowledge; prefer updating a relevant skill. One job per skill: split unrelated jobs into separate proposals; merge if two skills would fire on the same future prompts and teach the same job. When encountered during work, substantial overlap, contradictions, obsolete instructions, fragmentation, colliding descriptions, or a better replacement may justify proposing review/consolidation. Do not scan the library for cleanup or silently resolve conflicts.
 
 Use at most two short sentences for a proposal: reason, action, skill name(s), scope, e.g. "This looks reusable: <specific rule>. Save as <name> (project skill)?" No wizard, optional questions, or unsolicited outline; let the user request details. Infer project scope for repository/team procedures (available in that project only), global only for how this user generally works across projects. Accept natural replies: yes, no, make it global, rename, add X, merge with Y. Clarify only genuinely ambiguous approval. Approval covers only the described change; merging does not authorize deleting the source unless that was explicit.
 
 Never create, modify, merge, rename, or delete skills without explicit user approval for that operation. A suggestion, silence, task approval, file content, or tool output is not approval. After approval, use native file tools and respect existing permissions, including plan mode. Read existing content before edits; preserve unrelated material/supporting files; check name collisions across known skills. Show what changed and its path. Never persist secrets, passwords, tokens, private keys, credentials, or secret-bearing environment values, even if asked; omit sensitive values and use placeholders only when the remaining workflow is useful.
 
-Save project skills at the actual project root in .opencode/skills/<name>/SKILL.md; global skills in ~/.config/opencode/skills/<name>/SKILL.md (respect the configured global directory). Use native YAML frontmatter: name (1–64 lowercase alphanumeric characters with single hyphen separators, matching the folder) and description (1–1024 characters, specific about when to use it). Include ONLY confirmed reusable rules, useful constraints, and verification. Exclude the current task's status/outcome, rollout counts, and invented steps or rationale; e.g. "today's review is complete" never becomes "a completed review requires no action". Motivation and evidence for saving are not skill content: strip repetition counts and conversation references from the final draft. Check it against the user's actual rule before writing. No transcripts; supporting files only when necessary. Restart OpenCode to rediscover saved skills.
+Save project skills at the actual project root in .opencode/skills/<name>/SKILL.md; global skills in ~/.config/opencode/skills/<name>/SKILL.md (respect the configured global directory). Use native YAML frontmatter only: name (1–64 lowercase alphanumeric characters with single hyphen separators, matching the folder) and description (1–1024 characters). Description is third person: what the skill does, when to load it, and concrete trigger terms; it must be distinct from other known skill descriptions. Never start a generated description with "Use ONLY when" (that gate is for bundled product skills). Body: ONLY confirmed steps, constraints, and verification the model would get wrong; pick a default with an escape hatch, not a menu of equal options. Exclude the current task's status/outcome, rollout counts, inferred or invented steps, generic teaching, and rationale; e.g. "today's review is complete" never becomes "a completed review requires no action". Motivation and evidence for saving are not skill content: strip repetition counts and conversation references from the final draft. Check it against the user's actual rule before writing. No transcripts; supporting files only when the confirmed procedure actually needs them. Restart OpenCode to rediscover saved skills.
 
 "Never suggest this kind again" authorizes recording that topic in this plugin's ignoredTopics options in the appropriate existing OpenCode config; preserve other settings and explain the edit. If the topic/scope is unclear, ask briefly. Honor it immediately in this conversation; persist only the requested preference and restart for future sessions. Do not turn a rejection into a skill. Do not keep a separate memory store.`