Add `ai/` integration docs w/ `/commit-msg` usage
Deats, - top-level `ai/README.md` w/ integration table, conventions, and links to PR #69 (origin) + issue #79 (tracking) - `ai/claude-code/README.md` covering all 5 skills (summary table) and full `/commit-msg` usage guide: invocation, `$ARGUMENTS`, output format/files, frontmatter reference, dynamic context explanation (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-codeclaudy_skillz
parent
b23285bbda
commit
0134b94db0
|
|
@ -0,0 +1,50 @@
|
|||
# AI Tooling Integrations
|
||||
|
||||
Documentation and usage guides for AI-assisted
|
||||
development tools integrated with this repo.
|
||||
|
||||
Each subdirectory corresponds to a specific AI tool
|
||||
or frontend and contains usage docs for the
|
||||
custom skills/prompts/workflows configured for it.
|
||||
|
||||
Originally introduced in
|
||||
[PR #69](https://www.pikers.dev/pikers/piker/pulls/69);
|
||||
track new integration ideas and proposals in
|
||||
[issue #79](https://www.pikers.dev/pikers/piker/issues/79).
|
||||
|
||||
## Integrations
|
||||
|
||||
| Tool | Directory | Status |
|
||||
|------|-----------|--------|
|
||||
| [Claude Code](https://github.com/anthropics/claude-code) | [`claude-code/`](claude-code/) | active |
|
||||
|
||||
## Adding a New Integration
|
||||
|
||||
Create a subdirectory named after the tool (use
|
||||
lowercase + hyphens), then add:
|
||||
|
||||
1. A `README.md` covering setup, available
|
||||
skills/commands, and usage examples
|
||||
2. Any tool-specific config or prompt files
|
||||
|
||||
```
|
||||
ai/
|
||||
├── README.md # <- you are here
|
||||
├── claude-code/
|
||||
│ └── README.md
|
||||
├── opencode/ # future
|
||||
│ └── README.md
|
||||
└── <your-tool>/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- Skill/command names use **hyphen-case**
|
||||
(`commit-msg`, not `commit_msg`)
|
||||
- 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
|
||||
source files (under `.claude/skills/`, etc.)
|
||||
rather than duplicating content
|
||||
|
|
@ -0,0 +1,183 @@
|
|||
# Claude Code Integration
|
||||
|
||||
[Claude Code](https://github.com/anthropics/claude-code)
|
||||
skills and workflows for piker development.
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Invocable | Description |
|
||||
|-------|-----------|-------------|
|
||||
| [`commit-msg`](#commit-msg) | `/commit-msg` | Generate piker-style commit messages |
|
||||
| `piker-profiling` | auto | `Profiler` API patterns for perf work |
|
||||
| `piker-slang` | auto | Communication style + slang guide |
|
||||
| `pyqtgraph-optimization` | auto | Batch rendering patterns |
|
||||
| `timeseries-optimization` | auto | NumPy/Polars perf patterns |
|
||||
|
||||
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
|
||||
`.claude/skills/<skill-name>/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## `/commit-msg`
|
||||
|
||||
Generate piker-style git commit messages trained on
|
||||
500+ commits from the repo history.
|
||||
|
||||
### Quick Start
|
||||
|
||||
```
|
||||
# basic - analyzes staged diff automatically
|
||||
/commit-msg
|
||||
|
||||
# with scope hint
|
||||
/commit-msg .ib.feed: fix bar trimming
|
||||
|
||||
# with description context
|
||||
/commit-msg refactor position tracking
|
||||
```
|
||||
|
||||
### What It Does
|
||||
|
||||
1. **Reads staged changes** via dynamic context
|
||||
injection (`git diff --staged --stat`)
|
||||
2. **Reads recent commits** for style reference
|
||||
(`git log --oneline -10`)
|
||||
3. **Generates** a commit message following
|
||||
piker conventions (verb choice, backtick refs,
|
||||
colon prefixes, section markers, etc.)
|
||||
4. **Writes** the message to two files:
|
||||
- `.claude/<timestamp>_<hash>_commit_msg.md`
|
||||
- `.claude/git_commit_msg_LATEST.md`
|
||||
(overwritten each time)
|
||||
|
||||
### Arguments
|
||||
|
||||
The optional argument after `/commit-msg` is
|
||||
passed as `$ARGUMENTS` and used as scope or
|
||||
description context. Examples:
|
||||
|
||||
| Invocation | Effect |
|
||||
|------------|--------|
|
||||
| `/commit-msg` | Infer scope from diff |
|
||||
| `/commit-msg .ib.feed` | Use `.ib.feed:` prefix |
|
||||
| `/commit-msg fix the null seg crash` | Use as description hint |
|
||||
|
||||
### Output Format
|
||||
|
||||
**Subject line:**
|
||||
- ~50 chars target, 67 max
|
||||
- Present tense verb (Add, Drop, Fix, Factor..)
|
||||
- Backtick-wrapped code refs
|
||||
- Optional module prefix (`.ib.feed: ...`)
|
||||
|
||||
**Body** (when needed):
|
||||
- 67 char line max
|
||||
- Section markers: `Also,`, `Deats,`, `Further,`
|
||||
- `-` bullet lists for multiple changes
|
||||
- Piker abbreviations (`msg`, `mod`, `impl`,
|
||||
`deps`, `bc`, `obvi`, `prolly`..)
|
||||
|
||||
**Footer** (always):
|
||||
```
|
||||
(this patch was generated in some part by
|
||||
[`claude-code`][claude-code-gh])
|
||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
||||
```
|
||||
|
||||
### Output Files
|
||||
|
||||
After generation, the commit message is written to:
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── <timestamp>_<hash>_commit_msg.md # archived
|
||||
└── git_commit_msg_LATEST.md # latest
|
||||
```
|
||||
|
||||
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`:
|
||||
|
||||
```bash
|
||||
git commit -F .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
|
||||
|
||||
**Simple one-liner output:**
|
||||
```
|
||||
Add `MktPair.fqme` property for symbol resolution
|
||||
```
|
||||
|
||||
**Multi-file change output:**
|
||||
```
|
||||
Factor `.claude/skills/` into proper subdirs
|
||||
|
||||
Deats,
|
||||
- `commit_msg/` -> `commit-msg/` w/ enhanced
|
||||
frontmatter
|
||||
- all background skills set `user-invocable: false`
|
||||
- content split into supporting files
|
||||
|
||||
(this patch was generated in some part by
|
||||
[`claude-code`][claude-code-gh])
|
||||
[claude-code-gh]: https://github.com/anthropics/claude-code
|
||||
```
|
||||
|
||||
### Frontmatter Reference
|
||||
|
||||
The skill's `SKILL.md` uses these Claude Code
|
||||
frontmatter fields:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: commit-msg
|
||||
description: >
|
||||
Generate piker-style git commit messages...
|
||||
argument-hint: "[optional-scope-or-description]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools:
|
||||
- Bash(git *)
|
||||
- Read
|
||||
- Grep
|
||||
- Glob
|
||||
- Write
|
||||
---
|
||||
```
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `argument-hint` | Shows hint in autocomplete |
|
||||
| `disable-model-invocation` | Only user can trigger via `/commit-msg` |
|
||||
| `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.
|
||||
Loading…
Reference in New Issue