Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Persist localized Skill edits and resolve exact read references

wytc0800e00ef38
diff --git a/resources/builtin/_manifest.json b/resources/builtin/_manifest.json
index 91b36cea..8485d24f 100644
--- a/resources/builtin/_manifest.json
+++ b/resources/builtin/_manifest.json
@@ -1,6 +1,6 @@
{
"schema": 1,
- "content_tree_sha256": "072b2380f61351ad62e826097232c1dbc2ae3ebb61973ad58ed58f909162245c",
+ "content_tree_sha256": "0e78e96e8b9b5abf21a7977610c05c909e5582414d43da4710e36303fa6111b5",
"files": [
{
"path": "marketplace/agents/1040b336306f/agent.json",
@@ -1770,7 +1770,7 @@
{
"path": "system/skills/_system.json",
"bytes": 273,
- "sha256": "4a0e971481b9b6032914069a0ff08638c16ded94bb2d3a0ecbb1cc6030c84f08"
+ "sha256": "dfa3d511c76ef69f6c376b3d8e6d74f95ae39d1ed8151e6b9e261cd76a57e359"
},
{
"path": "system/skills/agent-creator/references/cli-and-prose.md",
@@ -1819,8 +1819,8 @@
},
{
"path": "system/skills/skill-creator/SKILL.md",
- "bytes": 7611,
- "sha256": "1b1c0fe62c8fa7dfe45cc0dc3139a25e7dc1e58c8e05e929b12640175ac42d38"
+ "bytes": 7615,
+ "sha256": "6bc6ce7ba58505d181f03dd69b66d5b7c1639099166569ca119f7fa72f3eaf91"
},
{
"path": "system/skills/web-app-sdk/assets/starter/index.html",
@@ -1885,7 +1885,7 @@
},
{
"id": "skill-creator",
- "update_at": 1792125132889
+ "update_at": 1792221336825
},
{
"id": "web-app-sdk",
diff --git a/resources/builtin/system/skills/_system.json b/resources/builtin/system/skills/_system.json
index ee6608c0..cbc96841 100644
--- a/resources/builtin/system/skills/_system.json
+++ b/resources/builtin/system/skills/_system.json
@@ -9,7 +9,7 @@
},
{
"id": "skill-creator",
- "update_at": 1792125132889
+ "update_at": 1792221336825
},
{
"id": "web-app-sdk",
diff --git a/resources/builtin/system/skills/skill-creator/SKILL.md b/resources/builtin/system/skills/skill-creator/SKILL.md
index 33094944..05b8c8af 100644
--- a/resources/builtin/system/skills/skill-creator/SKILL.md
+++ b/resources/builtin/system/skills/skill-creator/SKILL.md
@@ -38,7 +38,7 @@ Do not read unrelated references. A category-only edit needs only `metadata.md`;
- Bound Skill editor: mutate the current Skill without an outer `<skill>` wrapper for ordinary file/meta edits.
- Unbound create: omit `<skill_id>` and include a complete new `SKILL.md` plus category.
-- Unbound edit: resolve the target and check its `Source` in Available skills or `skill_search` before reading files or preparing edits. For `Source: builtin` or `Source: platform`, explain that the platform Skill definition cannot be edited through chat and nothing changed; emit no mutation protocol and do not retry the edit. For `Source: custom`, obtain the current `<skill_id>`, read the current SKILL.md, and emit only changed metadata or whole files.
+- Unbound edit: resolve the target and check its `Source` in Available skills or `skill_search` before reading files or preparing edits. For `Source: builtin` or `Source: platform`, explain that the platform Skill definition cannot be edited through chat and nothing changed; emit no mutation protocol and do not retry the edit. For `Source: custom`, read SKILL.md via `@skill/<ref>`, put that ref in `<skill_id>`, and emit only changed metadata or whole files.
- Pure discussion or no actual change: emit no protocol.
Before a new Skill, compare its name and typical objects/actions with Available skills. If one substantially overlaps, stop and ask whether to use it or still create a new one. Otherwise create in the same turn.
diff --git a/src/main/features/group_chat/bus.ts b/src/main/features/group_chat/bus.ts
index 49800750..87c43f7f 100644
--- a/src/main/features/group_chat/bus.ts
+++ b/src/main/features/group_chat/bus.ts
@@ -1300,6 +1300,7 @@ export interface TaskTerminalEvent {
conversation_created_at?: string;
}
+
export type TaskTerminalListener = (event: TaskTerminalEvent) => void;
/**
@@ -7380,9 +7381,15 @@ async function runActorTurnWithDisplay(
// Apply each `<skill>` container independently. A failed container
// appends its own warning span and is omitted from createdSkills —
// the chip slot only fills when the spec was actually written.
- for (const container of skillR.containers) {
+ for (const extractedContainer of skillR.containers) {
+ // A `@skill/<ref>` edit target resolves through this run's bindings;
+ // an unknown ref fails here instead of reaching the create fallback.
+ const target = skillsFeat.resolveSkillContainerTarget(extractedContainer, runtimeSkillBindings);
+ const container = target.ok ? target.container : extractedContainer;
try {
- let result = await skillsFeat.applySkillContainerFromCommander(container, { isCancelled: () => w.stopRequested || getActiveUserId() !== uid });
+ let result: Awaited<ReturnType<typeof skillsFeat.applySkillContainerFromCommander>> = target.ok === false
+ ? { ok: false, error: target.error }
+ : await skillsFeat.applySkillContainerFromCommander(container, { isCancelled: () => w.stopRequested || getActiveUserId() !== uid });
if (!result.ok && !errText && !aborted && !w.stopRequested
&& skillR.containers.length === 1 && !r.blocks.length
&& !toolCreatedSkills.length && !terminalHandoffCompleted
diff --git a/src/main/features/skills.ts b/src/main/features/skills.ts
index 0ea5fb59..f7dc9251 100644
--- a/src/main/features/skills.ts
+++ b/src/main/features/skills.ts
@@ -2557,7 +2557,9 @@ interface SkillMetadataApplyResult {
name?: string;
written: boolean;
report?: QualityReport;
- reason?: WriteSkillFileResult['reason'];
+ /** `not_applied`: the write finished but the Skill does not report the
+ * requested description, so the edit must not be presented as done. */
+ reason?: WriteSkillFileResult['reason'] | 'not_applied';
}
export async function applySkillMetadataForEdit(
@@ -2572,18 +2574,47 @@ export async function applySkillMetadataForEdit(
}
const mdPath = path.join(skill.dir, 'SKILL.md');
const current = fs.existsSync(mdPath) ? fs.readFileSync(mdPath, 'utf8') : '';
- const next = _applyMetadataToSkillMdContent(current, updates, skill.id, skill.source);
+ const has = (key: keyof SkillMetadataUpdate) => Object.prototype.hasOwnProperty.call(updates, key);
+ // A custom Skill keeps one description in SKILL.md and stores a sidecar
+ // pair only when both languages exist. Resolve a one-sided localized edit
+ // against the current pair; otherwise the old SKILL.md description wins on
+ // read and the edit silently has no effect.
+ const localized = skill.source === 'custom' && (has('description_zh') || has('description_en'))
+ ? (() => {
+ const cur = _resolveSkillDescriptions(splitSkillMd(current).meta, readSkillOrkasMetaSync(skill.dir));
+ const lang = descriptionLang(getLanguage());
+ const legacy = has('description') ? _normalizeDisplayDescription(String(updates.description || '')) : '';
+ let zh = has('description_zh') ? _normalizeDisplayDescription(String(updates.description_zh || '')) : cur.description_zh;
+ let en = has('description_en') ? _normalizeDisplayDescription(String(updates.description_en || '')) : cur.description_en;
+ if (legacy && lang === 'zh' && !has('description_zh')) zh = legacy;
+ if (legacy && lang !== 'zh' && !has('description_en')) en = legacy;
+ return { zh, en, primary: lang === 'zh' ? (zh || en) : (en || zh) };
+ })()
+ : null;
+ const mdUpdates: SkillMetadataUpdate = localized
+ ? (() => {
+ const next: SkillMetadataUpdate = { ...updates, description: localized.primary };
+ delete next.description_zh;
+ delete next.description_en;
+ return next;
+ })()
+ : updates;
+ const next = _applyMetadataToSkillMdContent(current, mdUpdates, skill.id, skill.source);
const rawSidecarPatch = _skillSidecarPatchFromMetadataUpdate(updates);
- const sidecarPatch = skill.source === 'marketplace'
+ const sidecarPatch = skill.source === 'marketplace' || localized
? _stripSkillSidecarDescriptions(rawSidecarPatch)
: rawSidecarPatch;
const writesMarkdown = next !== current;
if (writesMarkdown && skill.source !== 'custom') return { ok: false, skillId, written: false };
- const wrote = writesMarkdown || _hasSkillSidecarPatch(sidecarPatch);
+ const wrote = writesMarkdown || _hasSkillSidecarPatch(sidecarPatch) || !!localized;
const currentSidecar = readSkillOrkasMetaSync(skill.dir);
const proposedSidecar = opts.replaceSidecar && _hasSkillSidecarPatch(sidecarPatch)
? _stripSkillSidecarDescriptions(_skillSidecarReplacementFromMetadataUpdate(updates, currentSidecar))
: mergeSkillOrkasMeta(currentSidecar, sidecarPatch);
+ if (localized) {
+ if (localized.zh && localized.en) proposedSidecar.descriptions = { zh: localized.zh, en: localized.en };
+ else delete proposedSidecar.descriptions;
+ }
if (wrote && skill.source === 'custom') delete proposedSidecar._import;
const policyReports = await validateWithOperatorPolicy(uid, { kind: 'files', files: [
{ relpath: 'SKILL.md', content: next }, { relpath: '_meta.json', content: JSON.stringify(proposedSidecar, null, 2) },
@@ -2598,7 +2629,7 @@ export async function applySkillMetadataForEdit(
if (writesMarkdown && !_writeSkillFileAt(skill.dir, 'SKILL.md', next)) {
return { ok: false, skillId, written: false, report, reason: 'invalid_path' };
}
- if (_hasSkillSidecarPatch(sidecarPatch) || (wrote && currentSidecar._import)) {
+ if (localized || _hasSkillSidecarPatch(sidecarPatch) || (wrote && currentSidecar._import)) {
writeJsonSync(skillMetaFile(skill.dir), proposedSidecar);
_invalidateSkillListCache();
invalidateCoreAgentSkills().catch(() => { /* runner may not be loaded yet */ });
@@ -2610,6 +2641,15 @@ export async function applySkillMetadataForEdit(
const newId = await _renameSkillByFrontmatterIfNeeded(skillId, opts.isCancelled);
if (newId && newId !== skillId) resolvedId = newId;
}
+ if (localized) {
+ const persisted = await _getCustomSkillForUser(resolvedId, uid);
+ const applied = (!has('description_zh') || persisted?.description_zh === localized.zh)
+ && (!has('description_en') || persisted?.description_en === localized.en);
+ if (!applied) {
+ log.warn('description edit not reflected after write');
+ return { ok: false, skillId: resolvedId, written: wrote, reason: 'not_applied' };
+ }
+ }
const post = await getSkillForEdit(resolvedId);
log.info(`skill=${skillId}${resolvedId !== skillId ? ` -> ${resolvedId}` : ''} metadata updated`);
return { ok: true, skillId: resolvedId, name: post?.name || resolvedId, written: wrote, report };
@@ -3201,6 +3241,26 @@ export interface SkillContainerResult {
error?: string;
}
+const SKILL_READ_REF_TARGET_RE = /^@skill\/([^/\s]*)(\/.*)?$/;
+
+/** Resolve a run-scoped `@skill/<ref>` edit target to the host Skill id.
+ * The model edits the Skill it read through that ref, so the host id stays
+ * hidden from discovery results. Plain ids keep their existing behavior. An
+ * unknown or malformed ref is a failed edit, never a create: the missing-id
+ * create fallback must not turn a mistyped ref into a duplicate Skill. */
+export function resolveSkillContainerTarget(
+ container: SkillContainerExtracted,
+ bindings: ReadonlyMap<string, { id: string }>,
+): { ok: true; container: SkillContainerExtracted } | { ok: false; error: string } {
+ const raw = (container.skillId || '').trim();
+ const m = SKILL_READ_REF_TARGET_RE.exec(raw);
+ if (!m) return { ok: true, container };
+ const tail = (m[2] || '').replace(/\/+$/, '');
+ const binding = m[1] && (!tail || /^\/SKILL\.md$/i.test(tail)) ? bindings.get(m[1]) : undefined;
+ if (!binding) return { ok: false, error: t('skills.errors.skill_not_found', { id: raw }) };
+ return { ok: true, container: { ...container, skillId: binding.id } };
+}
+
/** Apply a parsed `<skill>` container from commander. Routes to edit when
* `container.skillId` resolves to an existing skill; otherwise a full
* SKILL.md payload is treated as create. This makes the commander path
diff --git a/test/main/features/group_chat/bus-integration.test.ts b/test/main/features/group_chat/bus-integration.test.ts
index 1a5ca9fb..c2b61bba 100644
--- a/test/main/features/group_chat/bus-integration.test.ts
+++ b/test/main/features/group_chat/bus-integration.test.ts
@@ -10494,3 +10494,59 @@ describe('group_chat bus integration › deferred conversation filing', () => {
},
);
});
+
+describe('group_chat bus integration › Commander Skill edit by read ref', () => {
+ // Discovery keeps host Skill ids hidden; Commander edits the Skill it found
+ // through the run-scoped `@skill/<ref>` returned by skill_search.
+ async function seedSkill(id: string) {
+ const paths = await import('../../../../src/main/paths');
+ const dir = path.join(paths.userSkillsDir(TEST_UID), id);
+ fs.mkdirSync(dir, { recursive: true });
+ fs.writeFileSync(path.join(dir, 'SKILL.md'),
+ `---\nname: "${id}"\ndescription: "Review release notes for refedit."\n---\n\n# Release review\n`);
+ return { paths, dir };
+ }
+
+ it('applies an edit addressed by the ref skill_search returned', async () => {
+ const cid = newCid();
+ const state = await import('../../../../src/main/features/group_chat/state');
+ const bus = await import('../../../../src/main/features/group_chat/bus');
+ const storage = await import('../../../../src/main/storage');
+ const { paths } = await seedSkill('refedit-notes');
+ _setScript(state.buildGconvSessionId(cid), [
+ { type: '__call_tool__', name: 'skill_search', input: { query: 'refedit' } },
+ { type: 'final', text: 'Updated.\n<skill>\n<skill_id>@skill/refedit-notes</skill_id>\n<description_en>Review release notes and report blocking evidence.</description_en>\n</skill>' },
+ ]);
+ await bus.enqueue({ uid: TEST_UID, cid, fromActorId: 'user', text: 'change the refedit Skill description' });
+ await waitForQuiescent(TEST_UID, cid, 5000);
+
+ const searched = JSON.parse(_recordedToolResults.find((entry) => entry.name === 'skill_search')?.content || '{}');
+ expect(searched.results?.[0]?.read_path).toBe('@skill/refedit-notes');
+ const skills = await import('../../../../src/main/features/skills');
+ expect((await skills.getCustomSkill('refedit-notes'))?.description_en)
+ .toBe('Review release notes and report blocking evidence.');
+ const messages = await storage.readJsonl<any>(path.join(paths.userChatsDir(TEST_UID), `${cid}.jsonl`));
+ expect(messages.flatMap((message: any) => message.created_skills || []))
+ .toEqual([expect.objectContaining({ skill_id: 'refedit-notes' })]);
+ }, 12_000);
+
+ it('rejects an unknown ref without creating a Skill from the attached SKILL.md', async () => {
+ const cid = newCid();
+ const state = await import('../../../../src/main/features/group_chat/state');
+ const bus = await import('../../../../src/main/features/group_chat/bus');
+ const storage = await import('../../../../src/main/storage');
+ const { paths } = await seedSkill('refedit-keep');
+ const before = fs.readdirSync(paths.userSkillsDir(TEST_UID)).sort();
+ _setScript(state.buildGconvSessionId(cid), [
+ { type: 'final', text: 'Done.\n<skill>\n<skill_id>@skill/refedit-missing</skill_id>\n<<<skill-file path=SKILL.md\n---\nname: "refedit-ghost"\ndescription: "Ghost."\n---\n\nBody\n>>>\n</skill>' },
+ ]);
+ await bus.enqueue({ uid: TEST_UID, cid, fromActorId: 'user', text: 'edit that Skill' });
+ await waitForQuiescent(TEST_UID, cid, 5000);
+
+ expect(fs.readdirSync(paths.userSkillsDir(TEST_UID)).sort()).toEqual(before);
+ const messages = await storage.readJsonl<any>(path.join(paths.userChatsDir(TEST_UID), `${cid}.jsonl`));
+ expect(messages.flatMap((message: any) => message.created_skills || [])).toHaveLength(0);
+ const reply = messages.filter((message: any) => message.from === 'commander').map((message: any) => String(message.text || '')).join('\n');
+ expect(reply).toMatch(/Skill not found: @skill\/refedit-missing|不存在|找不到/);
+ }, 12_000);
+});
diff --git a/test/main/features/skills.test.ts b/test/main/features/skills.test.ts
index 8bb22523..74725f87 100644
--- a/test/main/features/skills.test.ts
+++ b/test/main/features/skills.test.ts
@@ -633,6 +633,46 @@ describe('skills › applySkillContainerFromCommander › create', () => {
});
});
+describe('skills › resolveSkillContainerTarget', () => {
+ const bindings = new Map([
+ ['review-notes-1', { id: 'release-review-notes' }],
+ ['shipped-1', { id: 'shipped' }],
+ ]);
+ const container = (skillId?: string) => ({ skillId, files: [], metadata: { description_en: 'x' } });
+
+ it('maps the run-scoped read ref the model used to the host Skill id', async () => {
+ const s = await loadSkills();
+ for (const ref of ['@skill/review-notes-1', '@skill/review-notes-1/SKILL.md', ' @skill/review-notes-1/ ']) {
+ const r = s.resolveSkillContainerTarget(container(ref), bindings);
+ expect(r).toMatchObject({ ok: true, container: { skillId: 'release-review-notes', metadata: { description_en: 'x' } } });
+ }
+ });
+
+ it('keeps plain ids and create containers unchanged', async () => {
+ const s = await loadSkills();
+ expect(s.resolveSkillContainerTarget(container('release-review-notes'), bindings))
+ .toEqual({ ok: true, container: container('release-review-notes') });
+ expect(s.resolveSkillContainerTarget(container(undefined), bindings))
+ .toEqual({ ok: true, container: container(undefined) });
+ });
+
+ it('fails an unknown or malformed ref instead of falling back to create', async () => {
+ const s = await loadSkills();
+ for (const ref of ['@skill/unknown-9', '@skill/', '@skill/review-notes-1/references/a.md', '@skill/../x']) {
+ const r = s.resolveSkillContainerTarget({ ...container(ref), files: [{ path: 'SKILL.md', content: '---\nname: "x"\n---\n' }] }, bindings);
+ expect(r.ok, ref).toBe(false);
+ if (!r.ok) expect(r.error).toMatch(/not found|不存在|找不到/i);
+ }
+ });
+
+ it('does not treat look-alike ids as refs', async () => {
+ const s = await loadSkills();
+ for (const id of ['skill/review-notes-1', '@skills/review-notes-1', 'review-notes-1']) {
+ expect(s.resolveSkillContainerTarget(container(id), bindings)).toEqual({ ok: true, container: container(id) });
+ }
+ });
+});
+
describe('skills › applySkillContainerFromCommander › edit', () => {
it('writes blocks to existing custom skill', async () => {
writeCustomSkill('beta', 'name: "beta"\ndescription_en: "old"', 'old body');
@@ -671,6 +711,57 @@ describe('skills › applySkillContainerFromCommander › edit', () => {
expect(meta.category).toBe('data');
});
+ // A single-language description edit must persist and be what the Skill
+ // reports afterwards; the host previously wrote the old frontmatter
+ // description back and returned `updated` (2026-10-17 app-assist finding).
+ it.each(['en', 'zh'] as const)('persists a description_en-only edit on an English-only Skill (UI %s)', async (lang) => {
+ writeCustomSkill('review-notes', 'name: "review-notes"\ndescription: "Review release notes."', '# Release review\n');
+ const { setLanguage } = await import('../../../src/main/features/config');
+ setLanguage(lang);
+ const s = await loadSkills();
+ const r = await s.applySkillContainerFromCommander({
+ skillId: 'review-notes', files: [],
+ metadata: { description_en: 'Review release notes and report blocking evidence.' },
+ });
+ expect(r.ok).toBe(true);
+ const skill = await s.getCustomSkill('review-notes');
+ expect(skill?.description_en).toBe('Review release notes and report blocking evidence.');
+ const md = fs.readFileSync(path.join(customSkillsDir(), 'review-notes', 'SKILL.md'), 'utf8');
+ expect(md).toContain('# Release review');
+ expect(md).not.toContain('description_en:');
+ });
+
+ it.each([
+ ['en', 'description_en', '审查发布说明。', 'Review notes and blockers.'],
+ ['zh', 'description_en', '审查发布说明。', 'Review notes and blockers.'],
+ ['en', 'description_zh', '审查发布说明并报告阻塞证据。', 'Review release notes.'],
+ ['zh', 'description_zh', '审查发布说明并报告阻塞证据。', 'Review release notes.'],
+ ] as const)('keeps the other language when editing one side of a bilingual Skill (UI %s, %s)', async (lang, field, zh, en) => {
+ writeCustomSkill('bilingual', 'name: "bilingual"\ndescription: "Review release notes."', 'body');
+ fs.writeFileSync(path.join(customSkillsDir(), 'bilingual', '_meta.json'),
+ JSON.stringify({ descriptions: { zh: '审查发布说明。', en: 'Review release notes.' } }));
+ const { setLanguage } = await import('../../../src/main/features/config');
+ setLanguage(lang);
+ const s = await loadSkills();
+ const r = await s.applySkillContainerFromCommander({
+ skillId: 'bilingual', files: [], metadata: { [field]: field === 'description_en' ? en : zh },
+ });
+ expect(r.ok).toBe(true);
+ const skill = await s.getCustomSkill('bilingual');
+ expect(skill?.description_zh).toBe(zh);
+ expect(skill?.description_en).toBe(en);
+ });
+
+ it('accepts whitespace the host normalizes in a description edit', async () => {
+ writeCustomSkill('spacing', 'name: "spacing"\ndescription: "Old."', 'body');
+ const s = await loadSkills();
+ const r = await s.applySkillContainerFromCommander({
+ skillId: 'spacing', files: [], metadata: { description_en: 'New spaced\ndescription.' },
+ });
+ expect(r.ok).toBe(true);
+ expect((await s.getCustomSkill('spacing'))?.description_en).toBe('New spaced description.');
+ });
+
it('rejects edit on builtin skill (read-only outside dev panel)', async () => {
fs.mkdirSync(path.join(builtinSkillsDir(), 'shipped'), { recursive: true });
fs.writeFileSync(