Grayscale/obelisk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(docs): restructure SKILL.md into progressive-disclosure layers

Browse Source 
Split the monolithic skill prompt into three tiers:
  - Core API (search/context/sql) stays in the first prompt
  - Structured helpers listed as one-liners with filter signatures
  - Detailed patterns and pitfalls extracted to references/

  Add references/query-patterns.md (copyable CodeAct recipes) and
  references/pitfalls.md (scope, FTS, ordering, compactness traps).
  Clarify project scope semantics (slug vs path vs cwd) throughout.
  Add ORDER BY timestamp DESC to failures() for newest-first default.
This commit is contained in:
tommy0103
2026-06-07 16:42:41 +08:00
parent 67513b793f
commit 297ef01eaf
6 changed files with 701 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files
references/schema.md
+24 -6
View File
@@ -211,12 +211,22 @@ Full-text search across all message text using FTS5.
| `text` | `string` | FTS5 query (terms, phrases, prefix) |
| `opts.limit` | `number` | Max results (default 20) |
| `opts.sessionId` | `string` | Restrict to one session |
| `opts.project` | `string` | Restrict to a project slug |
| `opts.project` | `string` | SQL `LIKE` pattern over `sessions.project` |
| `opts.after` | `string` | ISO 8601 lower bound on timestamp |
| `opts.before` | `string` | ISO 8601 upper bound on timestamp |
| `opts.cwd` | `string` | Filter by working directory (supports LIKE) |
**Returns:** `Array<{ message, session, rank, context }>` where `context` is the 6 nearest messages by timestamp. `rank` is the FTS5 relevance score (negative; closer to 0 = more relevant).
**Scope note:** `sessions.project` is the stored Claude Code project slug,
`sessions.project_path` is the reconstructed absolute project path, and
`messages.cwd` is the working directory at message time. Helper `project`
filters are fuzzy `LIKE` filters over `sessions.project`. For exact project
membership, use `sql()` with `s.project = ?` or `s.project_path = ?`.
**Returns:** `Array<{ message, session, rank, context }>` where `context` is the
6 nearest messages by timestamp in the same session. It is temporal neighbor
context, not a parent chain. `rank` is the FTS5 relevance score used by
`ORDER BY rank`; lower values sort earlier, so treat the returned order as the
relevance order unless you are deliberately using FTS5 ranking details.
```js
const hits = search('MCTS exploration');
@@ -285,7 +295,7 @@ All subagent spawns, with message counts. For backward compatibility, passing a
| Param | Type | Description |
|-------|------|-------------|
| `opts.sessionId` | `string` | Restrict to one session |
| `opts.project` | `string` | Filter by project slug (LIKE) |
| `opts.project` | `string` | SQL `LIKE` pattern over `sessions.project` |
| `opts.limit` | `number` | Max results (default 100) |
**Returns:** `Array<{ ...subagent_row, messageCount }>`.
@@ -302,7 +312,7 @@ Workflow executions. For backward compatibility, passing a string is treated as
| Param | Type | Description |
|-------|------|-------------|
| `opts.sessionId` | `string` | Restrict to one session |
| `opts.project` | `string` | Filter by project slug (LIKE) |
| `opts.project` | `string` | SQL `LIKE` pattern over `sessions.project` |
| `opts.after` | `string` | ISO 8601 lower bound on timestamp |
| `opts.before` | `string` | ISO 8601 upper bound on timestamp |
| `opts.limit` | `number` | Max results (default 100) |
@@ -338,6 +348,9 @@ All tool calls that touched a specific file, across every session.
**Returns:** `Array<{ toolCall, session, timestamp }>`.
Default order is oldest first (`ORDER BY m.timestamp`). For recent file changes,
use raw SQL with `ORDER BY m.timestamp DESC`.
```js
const edits = fileHistory('/Users/tomiya/Code/quiet-zero/src/mcts.ts', { after: '2026-05-28' });
return edits.map(e => ({ tool: e.toolCall.name, session: e.session.title, time: e.timestamp }));
@@ -350,13 +363,15 @@ Tool calls whose results contain error patterns (`Error`, `ENOENT`, `failed`, `p
| Param | Type | Description |
|-------|------|-------------|
| `opts.sessionId` | `string` | Restrict to one session |
| `opts.project` | `string` | Filter by project slug (LIKE) |
| `opts.project` | `string` | SQL `LIKE` pattern over `sessions.project` |
| `opts.after` | `string` | ISO 8601 lower bound |
| `opts.before` | `string` | ISO 8601 upper bound |
| `opts.limit` | `number` | Max results (default 50) |
**Returns:** `Array<{ toolCall, result, session, nextMessages }>`.
Default order is newest first by the result message timestamp.
```js
const fails = failures({ project: '%quiet-zero%', limit: 10 });
return fails.map(f => ({ tool: f.toolCall?.name, error: f.result.content?.slice(0, 200) }));
@@ -379,7 +394,7 @@ Query sessions with filters. For backward compatibility, passing a number is tre
| Param | Type | Description |
|-------|------|-------------|
| `opts.project` | `string` | Filter by project slug (supports LIKE, e.g. `'%quiet-zero%'`) |
| `opts.project` | `string` | SQL `LIKE` pattern over `sessions.project` |
| `opts.after` | `string` | ISO 8601 lower bound on `started_at` |
| `opts.before` | `string` | ISO 8601 upper bound on `started_at` |
| `opts.limit` | `number` | Max results (default 50) |
@@ -389,6 +404,9 @@ Query sessions with filters. For backward compatibility, passing a number is tre
**Returns:** `Array<session_row>` ordered by `ended_at` descending.
For exact slug/path membership, use raw SQL with `project = ?` or
`project_path = ?`.
```js
const qz = sessions({ project: '%quiet-zero%', limit: 5 });
return qz.map(s => ({ title: s.title, branch: s.git_branch, ended: s.ended_at }));