[Feature] Skills 显示模式：仅列名称即可省下约 12k tokens/请求，所有技能仍可加载 / Skills display mode (full | names | off): ~12k fewer prompt tokens per request, all skills stay loadable

[fkhb90]

Problem / 问题

中文

• PI-Desktop 每一轮请求都会把所有可见 skill 的完整 id — name: description 塞进 system prompt 的 # Skills 区块。
• 实测：561 个已安装 skill、331 个可见时，该区块 73,130 bytes；395 个可见时 85,457 bytes，占固定前缀约 69%。
• 同一 session 实测固定前缀 token 长度：req1 = 29,479 tokens（占该轮 89,944 峰值上下文的 32.8%）。这部分成本每一轮都付一次（后续以 cacheRead 计费，但仍是同一个前缀在反复上传）。
• 这段内容是模型极少完整阅读的目录元数据：基准 session 中共 31 次工具调用，Skill 工具一次都没被用过。
• 目前没有任何开关可以调整。我已确认 app 设置模型只暴露 theme / mode / permissions / command shell / context usage display / large-paste threshold / font / language / proxy / contextCompaction，没有任何 skill 相关项；在 app.asar（main + renderer，49 个文件）中搜索 compact_all、skillsCompact、namesOnly、showDescriptions、hideDescriptions、descriptionMode、skillVisibility 等候选键，0 命中。

English

Every request injects the full id — name: description line for every visible skill into the # Skills block of the system prompt. Measured on a real install: 73,130 bytes with 331 visible skills; 85,457 bytes with 395 visible (≈69% of the fixed prefix). Measured fixed-prefix token length: 29,479 tokens at req1, i.e. 32.8% of that session's 89,944-token peak context — paid on every single request. In the baseline session, 31 tool calls were made and Skill was never used once.

There is no switch for this today. Verified: the settings model exposes theme, mode, permissions, command shell, context-usage display, large-paste threshold, font, language, proxy and contextCompaction — nothing skill-related; and a targeted search of app.asar (main + renderer, 49 files) for compact_all, skillsCompact, namesOnly, showDescriptions, hideDescriptions, descriptionMode, skillVisibility returns zero hits.

Relevant code, resources/agent-runtime/sidecar.js:

// src/plugin-skills-prompt.ts
function pluginSkillsPrompt(skills) {
  if (!skills.length) return void 0;
  return [
    "# Skills",
    "",
    `Plugins have taught you the following skills. ...`,
    "",
    ...skills.map((skill) => {
      const description = skill.description?.trim();
      return `- \`${skill.id}\` \u2014 ${skill.name}${description ? `: ${description}` : ""}`;
    })
  ].join("\n");
}

No mode switch, no truncation. Note the formatter already emits the names-only shape when description is absent.

Proposed change / 期望改动

新增一个 skills 显示模式设置（三个值），并可选加一个描述长度上限：

mode	输出	用途
full（默认，= 现状）	- `id` — Name: Description	现有用户行为不变
names	- `id` — Name	大型 skill 库推荐默认
off	省略整个 # Skills 区块	完全在别处管理 skill 的场景

可选：描述上限（字符数），给想要折衷的用户。

为什么 names 是最佳平衡点：每个 skill 的名称仍留在 prompt 里，可发现性不变——模型依然能看到全部 id，并可用 Skill 工具载入任何一个（该工具本来就会重新读取完整正文，且 pluginSkillsDigest 已把正文排除在快取摘要之外）。消失的只是那一行简介，而同一区块本来就在告诉模型「先读完整 skill 文件再动手」。

实测（真实 331 个可见 skill）：

变体	区块 bytes	相对现状	每请求省下的 tokens（@4.05–4.59 B/tok）
full（现状）	73,130	—	—
names only	19,190	−73.8%	−11,752 … −13,319
full，描述截到 120 字符	50,862	−30.4%	−4,851 … −5,498

最小改动：

function pluginSkillsPrompt(skills, mode = "full") {
  if (!skills.length || mode === "off") return void 0;
  return [
    "# Skills",
    "",
    `Plugins have taught you the following skills. ...`,
    "",
    ...skills.map((skill) => {
      const description = mode === "names" ? "" : skill.description?.trim();
      return `- \`${skill.id}\` \u2014 ${skill.name}${description ? `: ${description}` : ""}`;
    })
  ].join("\n");
}

两处调用点都要传入解析后的 mode（目前都写作 pluginSkillsPrompt(this.pluginSkills)）：

• RuntimeSession 构造 → 喂养 defaultSystemPrompt
• composeSystemPrompt() → if (tools.has(SKILL_TOOL_NAME)) { ... } 分支

快取安全要求（重要）

本 runtime 的 prompt 快取依赖前缀稳定，因此：

1. mode 必须在 session 建立时解析一次并保持不变，与目前的 baseSystemPrompt 相同；不要每轮重新读取设置。
2. mode 必须纳入 catalog digest（目前为 pluginSkillsDigest(this.pluginSkills) === pluginSkillsDigest(requestedPluginSkills)，用于让 runtime 退休并重建 prompt）。否则切换设置要么不生效，要么更糟——在 session 中途改变前缀、把快取整个打坏（我在实测中见过一次同类事件造成约 29k tokens 的重新前算）。

验收标准

1. names 模式下 # Skills 区块对每个 skill 都符合现有的「无描述」格式。
2. 切换模式在新 session 生效，且反映在 pluginSkillsDigest（runtime 会退休）。
3. 331 个 skill 的库，固定前缀下降 ≥ 11,000 tokens（可用下方方法验证）。
4. 所有 skill 名称仍然存在，且 Skill(id=…) 仍能载入每一个。
5. 稳态 cache hit 维持 ≥ 98%（基准 session 实测中位数 98.16%）。
6. Skill 工具描述仍说明如何载入，区块的引导句仍要求「先读完整文件再动手」。

Alternatives / 其他方案

• 只靠卸载/停用 skill — 已经可行，我也确实用这个方法砍掉了 64 个 skill。但它是钝器：用能力换 token，且每个 skill 都要人来判断。显示模式是用简介文字换 token，所有能力仍可触达。
• 把描述截断到 N 字符 — 可行的折衷（120 字符省 30.4%），但描述会读起来像被切断的片段，且仍留下约 50 KB。
• 直接缩短 SKILL.md 里的 description — 会伤害同一批文件的其他消费者（其他 agent、skill 列表 UI、人类阅读）。该修的是 prompt 的格式层，不是内容层。

另外：本提议与 #203（暴露 compaction 阈值）方向一致——都是把上下文预算交还给用户；与 #287 / #150（skill 市场、GitHub 链接）不冲突，可并存。

Additional context / 补充信息

数字怎么量出来的（可复现）

PI-Desktop 的序列化顺序是 [固定前缀][tools][对话]，供应商做前缀快取。当 tools 数组在 session 中途变动时，快取会刚好在固定前缀结尾断开，此时 cacheRead 就等于固定前缀 token 长度。 这个事件可以刻意触发：调用一次 ToolSearch 启用任一 on-demand 工具，然后读下一个请求的 usage。数据源：~/.pi-desktop/sessions/<id>.jsonl 中每条 assistant 消息的 meta.usage。

以此法取得的读数：

session	时点	断点处 cacheRead	触发
8d58db77	变更前	27,392	启用 Grep
3eac5178	停用 64 个 skill 后	24,704	启用 BrowserPreview

区块 bytes 的来源：skills 根目录下的 SKILL.md frontmatter（name、description），用 pluginSkillsPrompt() 的格式字符串重组后量 UTF-8 bytes。

环境：Windows 11、PI-Desktop 0.14.8、561 个已安装 skill（停用后 331 个可见）、provider opencode-go（https://opencode.ai/zen/go/v1）、model deepseek-v4.1-flash、上下文窗口 1M。

先例：Hermes Agent 已有等价开关 skills.compact_all: true，其文档描述为「system prompt 中的 skill 索引只显示 skill 名称（不含描述）……每个 skill 名称仍可见，且仍可透过 skill_view() 载入——只是丢掉描述」，并自估该区块省约 67%，与本次实测的 −73.8% 同量级。

建议标签：area: skills、enhancement（我没有 triage 权限，无法在提交时自行设置）。

提交前已检索全部 224 个 issue，未发现重复。

[fkhb90]

Minimal repro / 最小重現

A standalone, stdlib-only script that reproduces both numbers in this issue. It is read-only: it reads ~/.pi-desktop/sessions/*.jsonl (every assistant message stores the provider-reported meta.usage) and your skills root. No arguments needed beyond a session id.

一個獨立、僅用標準庫的腳本，可重現本 issue 的兩個數字。唯讀：只讀 ~/.pi-desktop/sessions/*.jsonl（每條 assistant 訊息都存有供應商回報的 meta.usage）與你的 skills 根目錄。

python repro-prefix-cost.py --session 8d58db77

(1) fixed-prefix token length, from session 8d58db77
session log   : C:\Users\fkhb9\.pi-desktop\sessions\8d58db77.jsonl
requests      : 20
req#1 ctx     : 29479 tokens  (prefix + first user message)
peak ctx      : 89944 tokens

cache breaks found (cacheRead = fixed prefix at that moment):
  req#   cacheRead   ctx        dctx   likely meaning
  #7        27392      58218    +2259   PREFIX ISOLATED

(2) `# Skills` block size, rebuilt from C:\Users\fkhb9\.agents\skills
skill packages on disk      : 560
visible after pinned hide   : 331
block, full descriptions    :   73130 bytes
block, names only           :   19190 bytes   (-73.8%)

Why cacheRead at a break equals the fixed-prefix length
The request is serialised as [fixed prefix][tools][conversation] and the provider does prefix caching, so when the tools array changes mid-session the cache must break exactly at the end of the fixed prefix. ToolSearch is the easiest way to force that change on purpose.

為什麼斷點處的 cacheRead 等於固定前綴長度
請求序列化為 [固定前綴][tools][對話]，供應商做前綴快取。當 tools 陣列在 session 中途變動時，快取必然在固定前綴結尾斷開。ToolSearch 是最容易刻意觸發這個變動的方式。

Clean-reading protocol / 取得乾淨讀數的協定

1. Start a fresh session. / 開一個全新 session。
2. Call ToolSearch once to activate any on-demand tool. / 呼叫一次 ToolSearch 啟用任一按需工具。
3. python repro-prefix-cost.py --session <that-id> — the break it reports is your prefix.
4. Long sessions that dispatch subagents interleave several request streams in one log, so they show many breaks; the script warns about this rather than pretending the smallest number is the prefix.

Take-away for this feature request
73,130 bytes of # Skills inside a 27,392-token fixed prefix. Dropping descriptions (names mode) removes ~74% of that block while every skill id stays in the prompt and stays loadable via the Skill tool.

repro-prefix-cost.py (full source)

#!/usr/bin/env python3
"""Measure PI-Desktop's fixed prompt-prefix cost. Standalone, stdlib only.

    python repro-prefix-cost.py                      # newest session + default skills root
    python repro-prefix-cost.py --session 8d58db77   # a specific session
    python repro-prefix-cost.py --skills-dir PATH    # override the skills root
    python repro-prefix-cost.py --list               # every session that has usage data

--------------------------------------------------------------------------------
MECHANISM (why this works)
--------------------------------------------------------------------------------
PI-Desktop serialises a request as  [fixed prefix][tools][conversation]  and the
provider does prefix caching. When the TOOLS ARRAY changes in the middle of a
session, the cache breaks exactly at the end of the fixed prefix, so the
provider reports

    cacheRead == fixed-prefix token length

A tools-array change is easy to trigger on purpose: call ToolSearch once to
activate any on-demand tool, then read the next request. That is how both
numbers below were obtained on a real install:

    session 8d58db77   cacheRead 27,392   (activating Grep)
    session 3eac5178   cacheRead 24,704   (activating BrowserPreview)

Reading `cacheRead` from a NORMAL request does not give you the prefix: it
includes the whole conversation up to that point. You need a break point.

The per-request numbers come from ~/.pi-desktop/sessions/<id>.jsonl: every
assistant message stores what the provider reported in meta.usage.
"""
import argparse
import datetime
import glob
import json
import os
import re
import sys

SESSIONS = os.path.expanduser(os.path.join('~', '.pi-desktop', 'sessions'))
DEFAULT_SKILLS = os.path.expanduser(os.path.join('~', '.agents', 'skills'))
PINNED_PREFIX = os.path.expanduser(os.path.join('~', '.pi-desktop',
                                                'agent-capabilities', 'skills.json'))


# ---------------------------------------------------------------- session logs
def load_session(path):
    reqs = []
    for line in open(path, encoding='utf-8'):
        if '"usage"' not in line:
            continue
        try:
            o = json.loads(line)
        except ValueError:
            continue
        u = (o.get('meta') or {}).get('usage')
        if not u:
            continue
        cr = u.get('cacheReadTokens') or 0
        reqs.append({'cr': cr, 'un': u.get('inputTokens') or 0,
                     'ctx': cr + (u.get('inputTokens') or 0)})
    return reqs


def find_breaks(reqs):
    """cacheRead fell while the context did not collapse -> prefix isolation."""
    out = []
    prev = None
    for i, r in enumerate(reqs, 1):
        if prev and prev['cr'] and r['cr'] and r['cr'] < prev['cr'] * 0.9:
            out.append({'i': i, 'before': prev['cr'], 'after': r['cr'],
                        'ctx': r['ctx'], 'dctx': r['ctx'] - prev['ctx']})
        if r['cr']:
            prev = r
    return out


def list_sessions():
    rows = []
    for p in glob.glob(os.path.join(SESSIONS, '*.jsonl')):
        r = load_session(p)
        if r:
            rows.append((os.path.basename(p)[:8], r,
                         datetime.datetime.fromtimestamp(os.path.getmtime(p))))
    rows.sort(key=lambda x: x[2], reverse=True)
    return rows


# ------------------------------------------------------------------ skills block
FRONT = re.compile(r'^---\s*\n([\s\S]*?)\n---')
HEADER = ('# Skills\n\nPlugins have taught you the following skills. Each entry is a set of '
          'instructions you can load with the `Skill` tool by passing its exact id. When a task '
          "matches a skill's description, load the skill first and follow it; do not guess at its "
          'content. Load each skill at most once per task.\n\n')


def read_skill(skill_md):
    txt = open(skill_md, encoding='utf-8', errors='replace').read()
    name, desc = os.path.basename(os.path.dirname(skill_md)), ''
    m = FRONT.match(txt)
    if m:
        mn = re.search(r'^name:\s*(.+)$', m.group(1), re.M)
        md = re.search(r'^description:\s*([\s\S]*?)(?=\n[a-zA-Z_-]+:|\Z)', m.group(1), re.M)
        if mn:
            name = mn.group(1).strip().strip('"\'')
        if md:
            desc = ' '.join(md.group(1).split()).strip().strip('"\'')
    return name, desc


def hidden_ids():
    if not os.path.isfile(PINNED_PREFIX):
        return set()
    try:
        d = json.loads(open(PINNED_PREFIX, encoding='utf-8-sig').read())
    except Exception:
        return set()
    out = set()
    for k, v in (d.get('values') or {}).items():
        try:
            o = json.loads(k)
        except ValueError:
            continue
        if o.get('kind') == 'skills' and v is False:
            out.add(o.get('id'))
    return out


def skills_block(skills_dir):
    per = {}
    for dp, dn, fn in os.walk(skills_dir, followlinks=True):
        if 'SKILL.md' not in fn:
            continue
        sid = os.path.relpath(dp, skills_dir).split(os.sep)[0]
        if sid not in per:
            per[sid] = read_skill(os.path.join(dp, 'SKILL.md'))
    hid = hidden_ids()
    vis = sorted(s for s in per if s not in hid)
    lines = ['- `%s` \u2014 %s%s'
             % (sid, per[sid][0], (': ' + per[sid][1]) if per[sid][1] else '')
             for sid in vis]
    full = HEADER + '\n'.join(lines)
    names = HEADER + '\n'.join('- `%s` — %s' % (s, per[s][0]) for s in vis)
    return len(per), len(vis), len(full.encode()), len(names.encode()), len(HEADER.encode())


# ----------------------------------------------------------------------- report
def main():
    ap = argparse.ArgumentParser()
    ap.add_argument('--session', default=None)
    ap.add_argument('--skills-dir', default=DEFAULT_SKILLS)
    ap.add_argument('--list', action='store_true')
    a = ap.parse_args()

    rows = list_sessions()
    if not rows:
        print('no session logs found in %s' % SESSIONS)
        return 1

    if a.list:
        print('%-10s %-19s %6s %10s %10s' % ('session', 'last write', 'reqs', 'req1', 'peak'))
        for sid, r, mt in rows:
            print('%-10s %-19s %6d %10d %10d'
                  % (sid, mt.strftime('%Y-%m-%d %H:%M'), len(r), r[0]['ctx'],
                     max(x['ctx'] for x in r)))
        return 0

    sid, reqs, mt = rows[0]
    if a.session:
        hit = [x for x in rows if x[0].startswith(a.session)]
        if not hit:
            print('no session matches %r' % a.session)
            return 1
        sid, reqs, mt = hit[0]

    print('=' * 74)
    print('(1) fixed-prefix token length, from session %s' % sid)
    print('=' * 74)
    print('session log   : %s' % os.path.join(SESSIONS, sid + '.jsonl'))
    print('requests      : %d' % len(reqs))
    print('req#1 ctx     : %d tokens  (prefix + first user message)' % reqs[0]['ctx'])
    print('peak ctx      : %d tokens' % max(r['ctx'] for r in reqs))
    print()
    br = find_breaks(reqs)
    if not br:
        print('no cache break found in this session.')
        print('To create one: in PI-Desktop, call ToolSearch once to activate an')
        print('on-demand tool, then re-run this script.')
    else:
        print('cache breaks found (cacheRead = fixed prefix at that moment):')
        print('  req#   cacheRead   ctx        dctx   likely meaning')
        for b in br:
            iso = abs(b['dctx']) < 12000
            print('  #%-5d %8d  %9d  %+7d   %s'
                  % (b['i'], b['after'], b['ctx'], b['dctx'],
                     'PREFIX ISOLATED' if iso else 'compaction (prefix also reported)'))
    print()

    print('=' * 74)
    print('(2) `# Skills` block size, rebuilt from %s' % a.skills_dir)
    print('=' * 74)
    if not os.path.isdir(a.skills_dir):
        print('skills dir not found: %s' % a.skills_dir)
        return 1
    total, vis, full, names, head = skills_block(a.skills_dir)
    print('skill packages on disk      : %d' % total)
    print('visible after pinned hide   : %d' % vis)
    print('block, full descriptions    : %7d bytes' % full)
    print('block, names only           : %7d bytes   (%+.1f%%)'
          % (names, (names / full - 1) * 100))
    print()
    print('Read these two numbers together: if the block is X bytes and the fixed')
    print('prefix is P tokens, the block occupies roughly X/4 of those P tokens.')
    print('It is the single largest component of the fixed prefix.')
    print()
    print('NOTE on (1): a session that dispatches subagents or runs auxiliary tasks')
    print('interleaves several request streams in one log, so many breaks appear and')
    print('the smallest one is not necessarily the prefix. For a clean reading use a')
    print('plain session: start one, call ToolSearch once to activate any on-demand')
    print('tool, then re-run this script for that session id.')
    return 0


if __name__ == '__main__':
    sys.exit(main())