Share piker skills across coding harnesses

Use portable Agent Skills metadata and one repo-local source for
both Claude Code and OpenCode.

Deats,
- replace harness-only frontmatter and dynamic context
- make `commit-msg` runtime-aware and review-first
- add a thin OpenCode command and integration docs
- guard `np.searchsorted()` guidance before OOB indexing
- record OpenCode prompt provenance

Prompt-IO: ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))

.claude/skills/commit-msg/SKILL.md

@@ -1,81 +1,116 @@
 ---
 name: commit-msg
 description: >
-  Generate piker-style git commit messages from
+  Generate piker-style git commit messages from staged
-  staged changes or prompt input, following the
+  changes or prompt input. Use when the user asks for a
-  style guide learned from 500 repo commits.
+  commit message or invokes a commit-message command.
-argument-hint: "[optional-scope-or-description]"
+compatibility: >
-disable-model-invocation: true
+  Requires git and a coding harness able to read and
-allowed-tools: Bash(git *), Read, Grep, Glob, Write
+  write files in the active checkout.
+metadata:
+  author: goodboy
+  version: "1.0"
 ---
 
-## Current staged changes
-!`git diff --staged --stat`
-
-## Recent commit style reference
-!`git log --oneline -10`
-
 # Piker Git Commit Message Generator
 
-Generate a commit message from the staged diff above
+Generate a commit message from the staged diff following
-following the piker project's conventions (learned from
+the piker project's conventions, learned from 500 repo
-analyzing 500 repo commits).
+commits.
-
-If `$ARGUMENTS` is provided, use it as scope or
-description context for the commit message.
 
 For the full style guide with verb frequencies,
 section markers, abbreviations, piker-specific terms,
 and examples, see
 [style-guide-reference.md](./style-guide-reference.md).
 
-## Quick Reference
+## Safety
+
+- Never run `git commit`, amend, rebase, merge, or push
+  unless the user explicitly requests that operation.
+- Do not stage or unstage files for a single-message run.
+- Never change issue, plan, or checklist state merely
+  because the related implementation is complete.
+- Preserve unrelated worktree changes.
+
+## Working Context
+
+1. Run `git rev-parse --show-toplevel`,
+   `git rev-parse --git-dir`, and
+   `git rev-parse --git-common-dir`.
+2. If the git dir differs from the common dir, report the
+   active worktree before generating the message.
+3. Inspect `git status --short`, the complete staged diff,
+   `git diff --staged --check`, and recent commit history.
+4. If nothing is staged, stop and tell the user. Prompt
+   text may clarify intent but does not replace a staged
+   patch unless the user explicitly asks for a draft with
+   no staged changes.
+
+## Message Style
 
 - **Subject**: ~50 chars, present tense verb, use
-  backticks for code refs
+  backticks for code refs; hard maximum 67 columns
 - **Body**: only for complex/multi-file changes,
-  67 char line max
+  filled close to a 67-column maximum
 - **Section markers**: Also, / Deats, / Other,
 - **Bullets**: use `-` style
 - **Tone**: technical but casual (piker style)
 
-## Claude-code Footer
+Use any user-supplied scope or description as context,
+but verify it against the staged patch. The message must
+describe the complete staged boundary, not only the most
+obvious file.
 
-When the written **patch** was assisted by
+## Provenance
-claude-code, include:
+
+If staged paths include prompt-I/O log entries under
+`ai/prompt-io/`, add one trailer per non-raw log file:
 
 ```
-(this patch was generated in some part by [`claude-code`][claude-code-gh])
+Prompt-IO: ai/prompt-io/<service>/<entry>.md
-[claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
-When only the **commit msg** was written by
+When the patch has substantive AI-authored changes but no
-claude-code (human wrote the patch), use:
+prompt-I/O entry is staged, remind the user that repository
+policy may require one. Do not block message generation.
+
+Always identify the active harness and model from runtime
+context rather than hardcoding Claude Code or OpenCode.
+
+When the harness assisted with the patch, append:
+
 ```
-(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
+(this patch was generated in some part by `<harness>` using `<model>` (`<provider>`))
-[claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
-## Output Instructions
+When it generated only the message, append:
 
-When generating a commit message:
+```
+(this commit msg was generated in some part by `<harness>` using `<model>` (`<provider>`))
+```
 
-1. Analyze the staged diff (injected above via
+## Output Files
-   dynamic context) to understand all changes.
+
-2. If `$ARGUMENTS` provides a scope (e.g.,
+Write the final message to both of these paths relative to
-   `.ib.feed`) or description, incorporate it into
+the active checkout returned by `git rev-parse
-   the subject line.
+--show-toplevel`:
-3. Write the subject line following verb + backtick
+
-   conventions from the
+- `.claude/skills/commit-msg/msgs/<timestamp>_<hash>_commit_msg.md`
-   [style guide](./style-guide-reference.md).
+- `.claude/git_commit_msg_LATEST.md`
-4. Add body only for multi-file or complex changes.
+
-5. Write the message to a file in the repo's
+Use UTC `<timestamp>` format `YYYYMMDDTHHMMSSZ` and the
-   `.claude/` subdir with filename format:
+first seven characters of the current `HEAD` hash. Create
-   `<timestamp>_<first-7-chars-of-last-commit-hash>_commit_msg.md`
+the archive directory when needed. The `.claude` path is a
-   where `<timestamp>` is from `date --iso-8601=seconds`.
+legacy repository artifact location shared by all coding
-   Also write a copy to
+harnesses; it does not imply which harness generated the
-   `.claude/git_commit_msg_LATEST.md`
+message.
-   (overwrite if exists).
+
+Finish by reporting both paths and this review-first
+command without running it:
+
+```
+git commit --edit --file .claude/git_commit_msg_LATEST.md
+```
 
 ---
 

.claude/skills/commit-msg/style-guide-reference.md

@@ -150,21 +150,18 @@ Common in piker commits (33.0% use colons):
 - File:line references not used (0 occurrences)
 - No WIP commits in analyzed set
 
-### Claude-code Footer
+### Coding-harness Footer
-When the written **patch** was assisted by claude-code,
+When a coding harness assisted with the written patch,
-include:
+identify the active harness, model, and provider:
 
 ```
-(this patch was generated in some part by [`claude-code`][claude-code-gh])
+(this patch was generated in some part by `<harness>` using `<model>` (`<provider>`))
-[claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
-When only the **commit msg** was written by claude-code
+When it generated only the commit message, use:
-(human wrote the patch), use:
 
 ```
-(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
+(this commit msg was generated in some part by `<harness>` using `<model>` (`<provider>`))
-[claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
 ## Piker-Specific Terms

.claude/skills/piker-conc-expert/SKILL.md

@@ -8,7 +8,12 @@ description: >
   eps), `to_asyncio` integration, cancellation
   semantics, or debugging hangs/wedges/skews in the
   actor system.
-user-invocable: false
+compatibility: >
+  Requires a piker checkout and familiarity with Python,
+  trio, and tractor.
+metadata:
+  author: goodboy
+  version: "1.0"
 ---
 
 # Piker Concurrency & Runtime Expertise

.claude/skills/piker-profiling/SKILL.md

@@ -5,7 +5,11 @@ description: >
   across distributed actor systems. Apply when
   adding profiling, debugging perf regressions, or
   optimizing hot paths in piker code.
-user-invocable: false
+compatibility: >
+  Requires a piker checkout and Python profiling work.
+metadata:
+  author: goodboy
+  version: "1.0"
 ---
 
 # Piker Profiling Subsystem

.claude/skills/piker-slang/SKILL.md

@@ -5,7 +5,11 @@ description: >
   ethos. Apply when communicating with piker devs,
   writing commit messages, code review comments, or
   any collaborative interaction.
-user-invocable: false
+compatibility: >
+  Harness-independent communication guidance.
+metadata:
+  author: goodboy
+  version: "1.0"
 ---
 
 # Piker Slang & Communication Style

.claude/skills/pyqtgraph-optimization/SKILL.md

@@ -5,7 +5,12 @@ description: >
   for piker's UI. Apply when optimizing graphics
   performance, adding new chart annotations, or
   working with `QGraphicsItem` subclasses.
-user-invocable: false
+compatibility: >
+  Requires a piker checkout with PyQtGraph and Qt source
+  available for inspection.
+metadata:
+  author: goodboy
+  version: "1.0"
 ---
 
 # PyQtGraph Rendering Optimization

.claude/skills/timeseries-optimization/SKILL.md

@@ -6,7 +6,12 @@ description: >
   with OHLCV arrays, timestamp lookups, gap
   detection, or any array/dataframe operations in
   piker.
-user-invocable: false
+compatibility: >
+  Requires a piker checkout with NumPy and optionally
+  Polars.
+metadata:
+  author: goodboy
+  version: "1.0"
 ---
 
 # Timeseries Optimization: NumPy & Polars
@@ -61,11 +66,14 @@ ts_array = np.array(timestamps)
 # binary search for all timestamps at once
 indices = np.searchsorted(time_arr, ts_array)
 
-# bounds check and exact match verification
+# bounds check before indexing: searchsorted may return
-valid_mask = (
+# len(time_arr) for values above the final timestamp
-    (indices < len(array))
+in_bounds = indices < len(time_arr)
-    &
+valid_mask = np.zeros(indices.shape, dtype=bool)
-    (time_arr[indices] == ts_array)
+valid_mask[in_bounds] = (
+    time_arr[indices[in_bounds]]
+    ==
+    ts_array[in_bounds]
 )
 
 valid_indices = indices[valid_mask]

.opencode/commands/commit-msg.md

@@ -0,0 +1,10 @@
+---
+description: Generate a piker-style message for staged changes.
+---
+
+Load the `commit-msg` skill and follow it completely for the currently
+staged changes. Do not run `git commit` unless the user explicitly asks.
+Keep all workflow and style decisions in the shared skill rather than
+duplicating them in this OpenCode command.
+
+Additional context from the user: $ARGUMENTS

ai/README.md

@@ -17,6 +17,18 @@ track new integration ideas and proposals in
 | Tool | Directory | Status |
 |------|-----------|--------|
 | [Claude Code](https://github.com/anthropics/claude-code) | [`claude-code/`](claude-code/) | active |
+| [OpenCode](https://opencode.ai/) | [`opencode/`](opencode/) | active |
+
+## Shared Skills
+
+Repo-specific skills use the portable Agent Skills
+frontmatter subset and live under `.claude/skills/` as a
+single source. Claude Code discovers that directory
+natively, and OpenCode discovers the same project skills
+without copies or generated wrappers.
+
+Harness-specific command files should only delegate to a
+shared skill. They must not duplicate the skill body.
 
 ## Adding a New Integration
 
@@ -32,7 +44,7 @@ ai/
 ├── README.md                  # <- you are here
 ├── claude-code/
 │   └── README.md
-├── opencode/                  # future
+├── opencode/
 │   └── README.md
 └── <your-tool>/
     └── README.md
@@ -45,6 +57,7 @@ ai/
 - Each integration doc should describe **what**
   the skill does, **how** to invoke it, and any
   **output** artifacts it produces
-- Keep docs concise; link to the actual skill
+- Keep docs concise; link to the shared skill source files
-  source files (under `.claude/skills/`, etc.)
   rather than duplicating content
+- Keep skill bodies harness-neutral; isolate slash-command
+  syntax and permissions in each harness integration

ai/claude-code/README.md

@@ -1,15 +1,17 @@
 # Claude Code Integration
 
 [Claude Code](https://github.com/anthropics/claude-code)
-skills and workflows for piker development.
+integration for piker's shared coding-harness skills.
 
 ## Skills
 
 | Skill | Invocable | Description |
 |-------|-----------|-------------|
 | [`commit-msg`](#commit-msg) | `/commit-msg` | Generate piker-style commit messages |
+| `piker-conc-expert` | auto | Actor-tree and structured-concurrency invariants |
 | `piker-profiling` | auto | `Profiler` API patterns for perf work |
 | `piker-slang` | auto | Communication style + slang guide |
+| `py-codestyle` | auto | Python source conventions |
 | `pyqtgraph-optimization` | auto | Batch rendering patterns |
 | `timeseries-optimization` | auto | NumPy/Polars perf patterns |
 
@@ -17,8 +19,10 @@ Skills marked **auto** are background knowledge
 applied automatically when Claude detects relevance.
 Only `commit-msg` is user-invoked via slash command.
 
-Skill source files live under
+Portable skill source files live under
-`.claude/skills/<skill-name>/SKILL.md`.
+`.claude/skills/<skill-name>/SKILL.md` and are shared with
+OpenCode. Claude-specific behavior belongs in command or
+settings files, not the shared skill bodies.
 
 ---
 
@@ -84,8 +88,7 @@ description context. Examples:
 **Footer** (always):
 ```
 (this patch was generated in some part by
-[`claude-code`][claude-code-gh])
+`claude-code` using `<model>` (`<provider>`))
-[claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
 ### Output Files
@@ -94,7 +97,8 @@ After generation, the commit message is written to:
 
 ```
 .claude/
-├── <timestamp>_<hash>_commit_msg.md   # archived
+├── skills/commit-msg/msgs/
+│   └── <timestamp>_<hash>_commit_msg.md
 └── git_commit_msg_LATEST.md           # latest
 ```
 
@@ -102,18 +106,10 @@ Where `<timestamp>` is ISO-8601 with seconds and
 `<hash>` is the first 7 chars of the current
 `HEAD` commit.
 
-Use the latest file to feed into `git commit`:
+Use the latest file with an editor review before commit:
 
 ```bash
-git commit -F .claude/git_commit_msg_LATEST.md
+git commit --edit --file .claude/git_commit_msg_LATEST.md
-```
-
-Or review/edit before committing:
-
-```bash
-cat .claude/git_commit_msg_LATEST.md
-# edit if needed, then:
-git commit -F .claude/git_commit_msg_LATEST.md
 ```
 
 ### Examples
@@ -128,56 +124,32 @@ Add `MktPair.fqme` property for symbol resolution
 Factor `.claude/skills/` into proper subdirs
 
 Deats,
-- `commit_msg/` -> `commit-msg/` w/ enhanced
+- use portable Agent Skills frontmatter
-  frontmatter
+- keep harness commands as thin delegates
-- all background skills set `user-invocable: false`
+- share supporting references across harnesses
-- content split into supporting files
 
 (this patch was generated in some part by
-[`claude-code`][claude-code-gh])
+`claude-code` using `<model>` (`<provider>`))
-[claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
-### Frontmatter Reference
+### Shared Frontmatter
 
-The skill's `SKILL.md` uses these Claude Code
+Skills use the Agent Skills fields understood by both
-frontmatter fields:
+Claude Code and OpenCode:
 
 ```yaml
 ---
 name: commit-msg
 description: >
-  Generate piker-style git commit messages...
+  Generate piker-style git commit messages. Use when...
-argument-hint: "[optional-scope-or-description]"
+compatibility: Requires git.
-disable-model-invocation: true
+metadata:
-allowed-tools:
+  author: goodboy
-  - Bash(git *)
+  version: "1.0"
-  - Read
-  - Grep
-  - Glob
-  - Write
 ---
 ```
 
-| Field | Purpose |
+Live git context is gathered by the skill at execution
-|-------|---------|
+time. Claude-only dynamic interpolation and tool-policy
-| `argument-hint` | Shows hint in autocomplete |
+frontmatter are intentionally excluded so another harness
-| `disable-model-invocation` | Only user can trigger via `/commit-msg` |
+can execute the same workflow.
-| `allowed-tools` | Tools the skill can use |
-
-### Dynamic Context
-
-The skill injects live data at invocation time
-via `!`backtick`` syntax in the `SKILL.md`:
-
-```markdown
-## Current staged changes
-!`git diff --staged --stat`
-
-## Recent commit style reference
-!`git log --oneline -10`
-```
-
-This means the staged diff stats and recent log
-are always fresh when the skill runs -- no stale
-context.

ai/opencode/README.md

@@ -0,0 +1,51 @@
+# OpenCode Integration
+
+[OpenCode](https://opencode.ai/) uses piker's shared
+repo-specific skills directly from `.claude/skills/`.
+There is no second copy of each skill to keep in sync.
+
+## Available Skills
+
+| Skill | Activation | Specialization |
+|-------|------------|----------------|
+| `commit-msg` | `/commit-msg` or explicit request | Piker commit-message style and artifacts |
+| `piker-conc-expert` | automatic | `tractor` actor topology, RPC, and cancellation |
+| `piker-profiling` | automatic | Cross-actor `Profiler` instrumentation |
+| `piker-slang` | automatic | Project communication style |
+| `py-codestyle` | automatic | Python source conventions |
+| `pyqtgraph-optimization` | automatic | Batched Qt graphics rendering |
+| `timeseries-optimization` | automatic | NumPy and Polars timeseries performance |
+
+OpenCode's project command lives at
+`.opencode/commands/commit-msg.md`. It delegates to the
+shared `commit-msg` skill and only supplies command
+arguments; workflow logic remains in the skill.
+
+A user-local skill with the same name may override a repo
+skill. Treat `opencode debug skill` as authoritative when
+diagnosing which source is active.
+
+## Verify Discovery
+
+From the repository root:
+
+```console
+opencode debug skill
+opencode debug config
+```
+
+`opencode debug skill` should list the piker skills from
+the project checkout. Restart OpenCode after changing a
+skill or command because configuration-time files are not
+hot-reloaded into an active session.
+
+## Portability Rules
+
+- Use only portable Agent Skills frontmatter in shared
+  `SKILL.md` files.
+- Keep harness-specific command syntax under
+  `.opencode/commands/`.
+- Detect the active harness and model at runtime; do not
+  hardcode Claude Code attribution in shared workflows.
+- Keep supporting references beside each shared skill so
+  relative links resolve in every harness.

ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md

@@ -0,0 +1,64 @@
+---
+model: gpt-5.6-sol
+provider: openai
+service: opencode
+session: ses_0799212ebffe42arY96czXn89F
+timestamp: 2026-07-21T20:52:28Z
+git_ref: 58ffe487
+scope: config
+substantive: true
+raw_file: 20260721T205228Z_58ffe487_prompt_io.raw.md
+---
+
+## Prompt
+
+The user asked to scan Claude's repo-local skills and
+documentation, summarize their specializations, and then
+rework repo-specific skills for use across coding
+harnesses, particularly OpenCode. The user intends to
+choose one of Claude's unfinished tasks afterward.
+
+## Response summary
+
+Standardized the tracked piker skills on portable Agent
+Skills frontmatter, made `commit-msg` harness-aware,
+documented OpenCode discovery and command delegation, and
+fixed an unsafe `np.searchsorted()` example found during
+the audit. Preserved the existing `.claude` artifact path
+as a shared legacy location to avoid breaking established
+commit workflows.
+
+## Files changed
+
+- `.claude/skills/commit-msg/SKILL.md` - portable,
+  harness-aware commit-message workflow
+- `.claude/skills/commit-msg/style-guide-reference.md` -
+  generic coding-harness attribution
+- `.claude/skills/piker-conc-expert/SKILL.md` - portable
+  frontmatter
+- `.claude/skills/piker-profiling/SKILL.md` - portable
+  frontmatter
+- `.claude/skills/piker-slang/SKILL.md` - portable
+  frontmatter
+- `.claude/skills/pyqtgraph-optimization/SKILL.md` -
+  portable frontmatter
+- `.claude/skills/timeseries-optimization/SKILL.md` -
+  portable frontmatter and safe search bounds handling
+- `ai/README.md` - shared-skill integration model
+- `ai/claude-code/README.md` - cross-harness Claude Code
+  documentation
+- `ai/opencode/README.md` - OpenCode usage and discovery
+  documentation
+- `.opencode/commands/commit-msg.md` - thin OpenCode
+  command delegating to the shared skill
+- `ai/prompt-io/opencode/README.md` - OpenCode provenance
+  policy
+- `ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md`
+  - unedited response record
+- `ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md`
+  - provenance metadata and summary
+
+## Human edits
+
+None - generated changes have not yet been reviewed or
+edited by the human.

ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md

@@ -0,0 +1,33 @@
+---
+model: gpt-5.6-sol
+provider: openai
+service: opencode
+timestamp: 2026-07-21T20:52:28Z
+git_ref: 58ffe487
+diff_cmd: git diff HEAD~1..HEAD
+---
+
+The repo-local skill inventory contains seven domains:
+commit-message generation, actor-runtime concurrency,
+distributed profiling, project communication style,
+Python source style, PyQtGraph rendering, and NumPy/Polars
+timeseries optimization.
+
+I converted the six tracked repo-specific skills to the
+portable Agent Skills frontmatter subset so Claude Code
+and OpenCode can load the same source files. The
+commit-message workflow now gathers live git context at
+execution time, uses runtime harness/model attribution,
+preserves human-owned task state, and keeps the existing
+message artifact paths for compatibility.
+
+I added OpenCode integration documentation and updated
+the shared and Claude Code docs to describe a single
+cross-harness skill source with thin harness commands.
+During validation I also corrected an out-of-bounds
+`np.searchsorted()` example in the timeseries skill.
+
+The unfinished artifacts found during the scan are a
+shared-memory migration plan and a gap-annotation
+performance handoff. The earlier datad split plan appears
+implemented and is now captured by the concurrency skill.

ai/prompt-io/opencode/README.md

@@ -0,0 +1,20 @@
+# AI Prompt I/O Log - OpenCode
+
+This directory tracks prompt inputs and model outputs for
+AI-assisted development using OpenCode.
+
+## Policy
+
+Prompt logging follows the
+[NLNet generative AI policy][nlnet-ai]. Substantive AI
+contributions are logged with the model, timestamp,
+prompt, response, and affected files.
+
+[nlnet-ai]: https://nlnet.nl/foundation/policies/generativeAI/
+
+## Usage
+
+Entries are created by the `prompt-io` skill. Human
+contributors remain accountable for all code decisions;
+AI-generated content is not presented as human-authored
+work.