From 84290684ab3ad2680243428e9886c7ccb5cd19fd Mon Sep 17 00:00:00 2001 From: Sawyer Date: Sun, 4 Oct 2026 23:49:51 -0700 Subject: [PATCH 1/5] docs(skills): record decision to keep first-party skills as SKILL.md --- docs/ARCHITECTURE.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d31ed9547..5d9ab7102 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -486,6 +486,21 @@ There is no skill `type` field required for model invocation — a skill body is Which plugin skill directories are in scope is decided in `runner.ts` / `skillDirsFromEnabledPlugins`, which passes the enabled plugins' dirs to both `discoverSkills` (for the listing) and the `use_skill` tool (for resolution). Project-local `.agents`/`.claude`/`.codex/skills` are always searched. Slash-command registration is first-wins (built-ins, then plugins in discovery order), so a first-party `/implement` stays first-party if a marketplace plugin of the same slash name is also enabled. +#### Decision CL-9805: first-party skills stay SKILL.md, not npm packages + +First-party skills remain Markdown capability packages (`SKILL.md`) shipped +in the bundled data-only `corbits-skills` plugin and scoped per director via +`attachedSkills` / `optionalSkills` (CL-9917). They do not become npm packages. + +Skills are prompt-time instruction text with no executable code, no build +step, and no versioned API surface, so an npm release and versioning +pipeline would have no consumer. Distribution and trust already ride the +plugin system (repo-origin auto-trust, `defaultEnabled`, the +`corbits-skills` id-collision guard). Director personas stay TypeScript +packages under `src/agent/directors//`; skill playbooks stay Markdown. +Revisit only if skills gain executable code or a versioned cross-repo +consumer. + ## Data Flow ``` From 07dd6c409a393d1e7919af8ee70101b6fbd40c9a Mon Sep 17 00:00:00 2001 From: Sawyer Date: Thu, 8 Oct 2026 19:57:49 -0700 Subject: [PATCH 2/5] docs(architecture): record skills stay markdown, not packages --- docs/ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5d9ab7102..ddb4f793a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -443,7 +443,7 @@ Known keybindings: `Ctrl+C` interrupts the in-flight run, and quits on a second ### Skills (`src/extensions/skills.ts`) -Skills are Markdown capability packages (`SKILL.md`). Each skill is a **dual surface**: the model looks up descriptions with the advertised `skill_search` catalog tool, loads a body on demand via the `use_skill` core tool, and the operator can invoke it as `/` unless frontmatter sets `user-invocable: false`. The primary prompt lists names only. `loadSkillCommands` (`src/plugins/skill-commands.ts`) synthesizes a slash command that sends the SKILL.md body (plus typed args) to the primary session; untagged skills still become slashes. +Skills stay Markdown content, not packages. Skills are `.md` capability packages (`SKILL.md`) authored under `plugins/`, enabled plugins, or `.agents`/`.claude`/`.codex/skills`. There is **no** `@corbits/code-agent-*`/workspace skill package and no `skills/` workspace extraction in 0.3.36. Each skill is a **dual surface**: the model looks up descriptions with the advertised `skill_search` catalog tool, loads a body on demand via the `use_skill` core tool, and the operator can invoke it as `/` unless frontmatter sets `user-invocable: false`. The primary prompt lists names only. `loadSkillCommands` (`src/plugins/skill-commands.ts`) synthesizes a slash command that sends the SKILL.md body (plus typed args) to the primary session; untagged skills still become slashes. Corbits Code **ships a bundled catalog** as the first-party data-only plugin `plugins/corbits-skills/` (id `corbits-skills`, kind `command`, `defaultEnabled: true`). Origin `repo` is auto-trusted. Auto-**enable** applies only when `origin === "repo"` AND `manifest.defaultEnabled` is true AND `settings.plugins[id]` is missing; an explicit `enabled: false` still disables. Marketplace (user / project / path / claude) `defaultEnabled` is ignored — those plugins stay opt-in. The id is `corbits-skills` (not `gaas`) so a later marketplace plugin cannot replace the module by id collision. From ba32206959c5a32458acdfe516e15f3c364cf567 Mon Sep 17 00:00:00 2001 From: Sawyer Date: Thu, 8 Oct 2026 19:59:48 -0700 Subject: [PATCH 3/5] docs(architecture): record skills stay markdown, not packages --- docs/ARCHITECTURE.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ddb4f793a..b5947cd98 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -486,21 +486,6 @@ There is no skill `type` field required for model invocation — a skill body is Which plugin skill directories are in scope is decided in `runner.ts` / `skillDirsFromEnabledPlugins`, which passes the enabled plugins' dirs to both `discoverSkills` (for the listing) and the `use_skill` tool (for resolution). Project-local `.agents`/`.claude`/`.codex/skills` are always searched. Slash-command registration is first-wins (built-ins, then plugins in discovery order), so a first-party `/implement` stays first-party if a marketplace plugin of the same slash name is also enabled. -#### Decision CL-9805: first-party skills stay SKILL.md, not npm packages - -First-party skills remain Markdown capability packages (`SKILL.md`) shipped -in the bundled data-only `corbits-skills` plugin and scoped per director via -`attachedSkills` / `optionalSkills` (CL-9917). They do not become npm packages. - -Skills are prompt-time instruction text with no executable code, no build -step, and no versioned API surface, so an npm release and versioning -pipeline would have no consumer. Distribution and trust already ride the -plugin system (repo-origin auto-trust, `defaultEnabled`, the -`corbits-skills` id-collision guard). Director personas stay TypeScript -packages under `src/agent/directors//`; skill playbooks stay Markdown. -Revisit only if skills gain executable code or a versioned cross-repo -consumer. - ## Data Flow ``` From d287003e8862a9d9b1985e877246ee27d8b8950c Mon Sep 17 00:00:00 2001 From: Sawyer Date: Thu, 8 Oct 2026 20:31:07 -0700 Subject: [PATCH 4/5] docs(architecture): tighten skills stay-markdown wording --- docs/ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b5947cd98..0b5c38f01 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -443,7 +443,7 @@ Known keybindings: `Ctrl+C` interrupts the in-flight run, and quits on a second ### Skills (`src/extensions/skills.ts`) -Skills stay Markdown content, not packages. Skills are `.md` capability packages (`SKILL.md`) authored under `plugins/`, enabled plugins, or `.agents`/`.claude`/`.codex/skills`. There is **no** `@corbits/code-agent-*`/workspace skill package and no `skills/` workspace extraction in 0.3.36. Each skill is a **dual surface**: the model looks up descriptions with the advertised `skill_search` catalog tool, loads a body on demand via the `use_skill` core tool, and the operator can invoke it as `/` unless frontmatter sets `user-invocable: false`. The primary prompt lists names only. `loadSkillCommands` (`src/plugins/skill-commands.ts`) synthesizes a slash command that sends the SKILL.md body (plus typed args) to the primary session; untagged skills still become slashes. +Skills stay Markdown content, not packages. There is **no** `@corbits/code-agent-*`/workspace skill package and no `skills/` workspace extraction in 0.3.36; skills are `.md` capability packages (`SKILL.md`) authored under `plugins/`, enabled plugins, or `.agents`/`.claude`/`.codex/skills`. Each skill is a **dual surface**: the model looks up descriptions with the advertised `skill_search` catalog tool, loads a body on demand via the `use_skill` core tool, and the operator can invoke it as `/` unless frontmatter sets `user-invocable: false`. The primary prompt lists names only. `loadSkillCommands` (`src/plugins/skill-commands.ts`) synthesizes a slash command that sends the SKILL.md body (plus typed args) to the primary session; untagged skills still become slashes. Corbits Code **ships a bundled catalog** as the first-party data-only plugin `plugins/corbits-skills/` (id `corbits-skills`, kind `command`, `defaultEnabled: true`). Origin `repo` is auto-trusted. Auto-**enable** applies only when `origin === "repo"` AND `manifest.defaultEnabled` is true AND `settings.plugins[id]` is missing; an explicit `enabled: false` still disables. Marketplace (user / project / path / claude) `defaultEnabled` is ignored — those plugins stay opt-in. The id is `corbits-skills` (not `gaas`) so a later marketplace plugin cannot replace the module by id collision. From fd98d3f8f9993885da2ae3163968ad21fc6e82cb Mon Sep 17 00:00:00 2001 From: "user.email" Date: Thu, 8 Oct 2026 20:33:50 -0700 Subject: [PATCH 5/5] docs(skills): tighten skills-remain-markdown wording --- docs/ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0b5c38f01..8e8397294 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -443,7 +443,7 @@ Known keybindings: `Ctrl+C` interrupts the in-flight run, and quits on a second ### Skills (`src/extensions/skills.ts`) -Skills stay Markdown content, not packages. There is **no** `@corbits/code-agent-*`/workspace skill package and no `skills/` workspace extraction in 0.3.36; skills are `.md` capability packages (`SKILL.md`) authored under `plugins/`, enabled plugins, or `.agents`/`.claude`/`.codex/skills`. Each skill is a **dual surface**: the model looks up descriptions with the advertised `skill_search` catalog tool, loads a body on demand via the `use_skill` core tool, and the operator can invoke it as `/` unless frontmatter sets `user-invocable: false`. The primary prompt lists names only. `loadSkillCommands` (`src/plugins/skill-commands.ts`) synthesizes a slash command that sends the SKILL.md body (plus typed args) to the primary session; untagged skills still become slashes. +Skills stay Markdown content, not packages — they are capability packages (`SKILL.md`). Each skill is a **dual surface**: the model looks up descriptions with the advertised `skill_search` catalog tool, loads a body on demand via the `use_skill` core tool, and the operator can invoke it as `/` unless frontmatter sets `user-invocable: false`. The primary prompt lists names only. `loadSkillCommands` (`src/plugins/skill-commands.ts`) synthesizes a slash command that sends the SKILL.md body (plus typed args) to the primary session; untagged skills still become slashes. Corbits Code **ships a bundled catalog** as the first-party data-only plugin `plugins/corbits-skills/` (id `corbits-skills`, kind `command`, `defaultEnabled: true`). Origin `repo` is auto-trusted. Auto-**enable** applies only when `origin === "repo"` AND `manifest.defaultEnabled` is true AND `settings.plugins[id]` is missing; an explicit `enabled: false` still disables. Marketplace (user / project / path / claude) `defaultEnabled` is ignored — those plugins stay opt-in. The id is `corbits-skills` (not `gaas`) so a later marketplace plugin cannot replace the module by id collision.