diff --git a/README.md b/README.md index e8c3398..74b9b21 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl ## Bundled Surface -- Commands cover direct work (`/ask`, `/commit`, `/merge`), orchestration (`/dev`, `/ship`, `/todo`), ticket planning/sync, and PR review/shipping flows. +- Commands cover direct work (`/ask`, `/commit`, `/merge`, `/skill/create`, `/skill/optimize`), orchestration (`/dev`, `/ship`, `/todo`), ticket planning/sync, and PR review/shipping flows. - Agents are intentionally narrow: `worker` is generic, `planner` is no-edit planning, `navigator` owns multi-step orchestration, and `reviewer` is a no-edit review specialist. - Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `command_expansion` (resolve a slash command and return the expanded prompt for immediate delegation), `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`. - Reusable command-template components live in `packages/core/components/` and are documented in the components reference. diff --git a/kompass.jsonc b/kompass.jsonc index 8b8a333..664c0df 100644 --- a/kompass.jsonc +++ b/kompass.jsonc @@ -22,6 +22,8 @@ "pr/fix": { "enabled": true }, "pr/review": { "enabled": true }, "review": { "enabled": true }, + "skill/create": { "enabled": true }, + "skill/optimize": { "enabled": true }, "ship": { "enabled": true }, "rmslop": { "enabled": true }, "todo": { "enabled": true }, @@ -55,6 +57,7 @@ "dev-flow": { "enabled": true }, "load-pr": { "enabled": true }, "load-ticket": { "enabled": true }, + "skill-authoring": { "enabled": true }, "summarize-changes": { "enabled": true }, }, diff --git a/kompass.schema.json b/kompass.schema.json index aed7d8d..dc9620d 100644 --- a/kompass.schema.json +++ b/kompass.schema.json @@ -65,6 +65,12 @@ "review": { "$ref": "#/$defs/commandConfig" }, + "skill/create": { + "$ref": "#/$defs/commandConfig" + }, + "skill/optimize": { + "$ref": "#/$defs/commandConfig" + }, "ship": { "$ref": "#/$defs/commandConfig" }, @@ -105,6 +111,8 @@ "pr/fix", "pr/review", "review", + "skill/create", + "skill/optimize", "ship", "rmslop", "todo", @@ -133,6 +141,8 @@ "pr/fix", "pr/review", "review", + "skill/create", + "skill/optimize", "ship", "rmslop", "todo", @@ -223,6 +233,9 @@ "load-ticket": { "$ref": "#/$defs/componentConfig" }, + "skill-authoring": { + "$ref": "#/$defs/componentConfig" + }, "summarize-changes": { "$ref": "#/$defs/componentConfig" }, @@ -230,7 +243,7 @@ "type": "array", "items": { "type": "string", - "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "summarize-changes"] + "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"] }, "uniqueItems": true, "deprecated": true @@ -238,7 +251,7 @@ "paths": { "type": "object", "propertyNames": { - "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "summarize-changes"] + "enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"] }, "additionalProperties": { "type": "string" diff --git a/packages/core/commands/index.ts b/packages/core/commands/index.ts index ed940ce..e4c3676 100644 --- a/packages/core/commands/index.ts +++ b/packages/core/commands/index.ts @@ -68,6 +68,16 @@ export const commandDefinitions: Record = { agent: "reviewer", templatePath: "commands/review.md", }, + "skill/create": { + description: "Create a focused Agent Skill from repo context", + agent: "worker", + templatePath: "commands/skill/create.md", + }, + "skill/optimize": { + description: "Improve an existing Agent Skill from real feedback", + agent: "worker", + templatePath: "commands/skill/optimize.md", + }, ship: { description: "Ship branch work through commit and PR creation", agent: "navigator", diff --git a/packages/core/commands/skill/create.md b/packages/core/commands/skill/create.md new file mode 100644 index 0000000..b59dab1 --- /dev/null +++ b/packages/core/commands/skill/create.md @@ -0,0 +1,70 @@ +## Goal + +Create a new Agent Skill from project context and user direction, producing a focused `SKILL.md` and only the supporting files that materially improve the skill. + +## Additional Context + +- Favor creation over revision: create the smallest correct first version of the skill from the gathered context +- Only add support files during creation when they clearly improve execution on day one + +## Workflow + +### Arguments + + +$ARGUMENTS + + +### Interpret Arguments + +- If `` contains a clear skill request, store it as `` +- If `` contains an explicit skill name, slug, or desired folder name, store it as `` +- If `` includes supporting context such as file paths, URLs, ticket references, or existing examples, store them as `` +- If `` includes constraints, audience, tools, or notes, store them as `` +- If `` is still missing, derive it from the conversation +- If the request still cannot be determined, STOP and report that skill direction is required + +### Load Starting Context + +- Inspect the repository for existing skills, skill roots, and nearby conventions before creating anything +- If the repo already uses one clear skill root, store it as `` +- Otherwise, store `.agents/skills` as `` +- Read only the relevant existing skills, docs, scripts, and project artifacts needed to ground the new skill +- If an existing skill already covers the same scope and the request does not clearly justify a separate skill, STOP and report the overlap instead of creating a duplicate + +<%~ include("@skill-authoring", { mode: "create" }) %> + +### Output + +If skill direction is missing, display: +``` +Skill direction required + +Provide the skill goal, workflow, or domain so the skill can be created. + +No additional steps are required. +``` + +If an existing skill already covers the scope, display: +``` +Skill already exists for this scope + +Existing skill: +Reason: + +No additional steps are required. +``` + +When the skill is created, display: +``` +Created skill: + +Path: /SKILL.md +Files: + + +Validation: + + +No additional steps are required. +``` diff --git a/packages/core/commands/skill/optimize.md b/packages/core/commands/skill/optimize.md new file mode 100644 index 0000000..aa8d430 --- /dev/null +++ b/packages/core/commands/skill/optimize.md @@ -0,0 +1,83 @@ +## Goal + +Improve an existing Agent Skill so it triggers more reliably, stays lean, and produces better outputs for the intended workflow. + +## Additional Context + +- Favor targeted iteration over full rewrites; keep what already works and change only the parts blocking activation or execution quality +- Prefer optimization grounded in real prompts, evals, reviewer feedback, transcripts, or repeated failures over speculative cleanup + +## Workflow + +### Arguments + + +$ARGUMENTS + + +### Interpret Arguments + +- If `` contains a skill path, folder, slug, or `SKILL.md` reference, store it as `` +- If `` includes an optimization focus such as triggering, output quality, evals, or excess complexity, store it as `` +- If `` includes evidence such as prompts, failing cases, reviewer feedback, transcripts, or related files, store it as `` +- If `` includes constraints, audience, tools, or notes, store them as `` +- If `` is still missing, derive it from the conversation +- If the target skill still cannot be determined, STOP and report that a skill reference is required + +### Load Skill Context + +- Resolve `` to the target skill directory and store it as `` +- Confirm `/SKILL.md` exists; if not, STOP and report that the skill could not be found +- Read the current `SKILL.md` +- Read only the support files that materially affect the optimization focus, such as `references/`, `scripts/`, `assets/`, `evals/`, or nearby docs +- If optimization evidence was provided through ``, load and use it as source context + +### Reapply Skill Workflow + +- Identify the smallest set of changes that will improve `` without rewriting working parts of the skill +- If the skill already matches the requested focus and no meaningful improvement is justified, STOP and report that no changes are needed + +<%~ include("@skill-authoring", { mode: "optimize" }) %> + +### Output + +If the target skill cannot be determined, display: +``` +Skill reference required + +Provide the skill path, folder, slug, or `SKILL.md` target to optimize. + +No additional steps are required. +``` + +If the target skill cannot be found, display: +``` +Skill not found + +Target: + +No additional steps are required. +``` + +If no meaningful optimization is needed, display: +``` +No skill changes needed + +Skill: +Reason: + +No additional steps are required. +``` + +When the skill is optimized, display: +``` +Optimized skill: + +Updated files: + + +Validation: + + +No additional steps are required. +``` diff --git a/packages/core/components/skill-authoring.md b/packages/core/components/skill-authoring.md new file mode 100644 index 0000000..caf50ea --- /dev/null +++ b/packages/core/components/skill-authoring.md @@ -0,0 +1,40 @@ +### Shared Skill Workflow + +#### Load Related Context + +- Read only the code, skills, scripts, docs, evals, and conversation context that materially affect this skill +- Ground decisions in project-specific patterns, successful examples, and repeated corrections rather than generic advice +- Use related skills to understand naming, boundaries, and overlap when they are relevant +- If optimizing an existing skill, treat the current skill and its support files as the source of truth before changing anything + +#### Design The Skill + +- Keep the skill to one coherent reusable job; narrow broad requests to the most reusable unit +- Prefer the smallest correct shape: start with `SKILL.md`, then add support files only when they materially help +<% if (it.mode === "create") { -%> +- Derive `` by preferring `` when it is valid; otherwise create a lowercase hyphenated name that matches the intended folder name and satisfies the Agent Skills naming rules +- Store the target directory as `` = `/` +<% } else { -%> +- Preserve the existing skill name and directory unless the user explicitly asked for a rename or move +- Store the working skill name as `` and keep `` as the target directory +<% } -%> +- Write the `description` as an imperative trigger instruction focused on user intent, such as `Use this skill when...` +- Prefer one clear default approach; mention alternatives only as explicit escape hatches +- Include gotchas, validation loops, examples, or output templates only when they materially improve execution +- Keep `SKILL.md` concise; move heavy detail to `references/`, `scripts/`, `assets/`, or `evals/` with explicit load conditions + +#### Write The Skill + +- Create or update `/SKILL.md` +- Keep frontmatter minimal: use `name` and `description`, and add optional fields only when they are justified +- Write concrete procedures and defaults instead of generic declarations +- Avoid empty directories, placeholder files, and speculative assets +- Store the changed file list as `` with one bullet per file path + +#### Validate The Skill + +- Confirm the directory name matches the skill name in frontmatter +- Confirm the frontmatter is valid and the description remains within the Agent Skills limits +- Confirm file references are relative to the skill root and point to real files +- If scripts or eval helpers were added or updated, run the most relevant available validation for those files +- Store the resulting validation summary as `` diff --git a/packages/core/kompass.jsonc b/packages/core/kompass.jsonc index 8b8a333..664c0df 100644 --- a/packages/core/kompass.jsonc +++ b/packages/core/kompass.jsonc @@ -22,6 +22,8 @@ "pr/fix": { "enabled": true }, "pr/review": { "enabled": true }, "review": { "enabled": true }, + "skill/create": { "enabled": true }, + "skill/optimize": { "enabled": true }, "ship": { "enabled": true }, "rmslop": { "enabled": true }, "todo": { "enabled": true }, @@ -55,6 +57,7 @@ "dev-flow": { "enabled": true }, "load-pr": { "enabled": true }, "load-ticket": { "enabled": true }, + "skill-authoring": { "enabled": true }, "summarize-changes": { "enabled": true }, }, diff --git a/packages/core/lib/config.ts b/packages/core/lib/config.ts index b07e7a1..eda73a2 100644 --- a/packages/core/lib/config.ts +++ b/packages/core/lib/config.ts @@ -33,6 +33,8 @@ export const DEFAULT_COMMAND_NAMES = [ "pr/fix", "pr/review", "review", + "skill/create", + "skill/optimize", "ship", "rmslop", "todo", @@ -52,6 +54,7 @@ export const DEFAULT_COMPONENT_NAMES = [ "dev-flow", "load-pr", "load-ticket", + "skill-authoring", "summarize-changes", ] as const; @@ -97,6 +100,8 @@ export interface KompassConfig { "pr/fix"?: CommandConfig; "pr/review"?: CommandConfig; review?: CommandConfig; + "skill/create"?: CommandConfig; + "skill/optimize"?: CommandConfig; ship?: CommandConfig; rmslop?: CommandConfig; todo?: CommandConfig; @@ -130,6 +135,7 @@ export interface KompassConfig { "dev-flow"?: ComponentConfig; "load-pr"?: ComponentConfig; "load-ticket"?: ComponentConfig; + "skill-authoring"?: ComponentConfig; "summarize-changes"?: ComponentConfig; enabled?: string[]; paths?: Record; @@ -443,6 +449,7 @@ const defaultComponentPaths: Record = { "dev-flow": "components/dev-flow.md", "load-pr": "components/load-pr.md", "load-ticket": "components/load-ticket.md", + "skill-authoring": "components/skill-authoring.md", "summarize-changes": "components/summarize-changes.md", }; diff --git a/packages/opencode/.opencode/commands/skill/create.md b/packages/opencode/.opencode/commands/skill/create.md new file mode 100644 index 0000000..01470bb --- /dev/null +++ b/packages/opencode/.opencode/commands/skill/create.md @@ -0,0 +1,109 @@ +--- +description: Create a focused Agent Skill from repo context +agent: worker +--- + +## Goal + +Create a new Agent Skill from project context and user direction, producing a focused `SKILL.md` and only the supporting files that materially improve the skill. + +## Additional Context + +- Favor creation over revision: create the smallest correct first version of the skill from the gathered context +- Only add support files during creation when they clearly improve execution on day one + +## Workflow + +### Arguments + + +$ARGUMENTS + + +### Interpret Arguments + +- If `` contains a clear skill request, store it as `` +- If `` contains an explicit skill name, slug, or desired folder name, store it as `` +- If `` includes supporting context such as file paths, URLs, ticket references, or existing examples, store them as `` +- If `` includes constraints, audience, tools, or notes, store them as `` +- If `` is still missing, derive it from the conversation +- If the request still cannot be determined, STOP and report that skill direction is required + +### Load Starting Context + +- Inspect the repository for existing skills, skill roots, and nearby conventions before creating anything +- If the repo already uses one clear skill root, store it as `` +- Otherwise, store `.agents/skills` as `` +- Read only the relevant existing skills, docs, scripts, and project artifacts needed to ground the new skill +- If an existing skill already covers the same scope and the request does not clearly justify a separate skill, STOP and report the overlap instead of creating a duplicate + +### Shared Skill Workflow + +#### Load Related Context + +- Read only the code, skills, scripts, docs, evals, and conversation context that materially affect this skill +- Ground decisions in project-specific patterns, successful examples, and repeated corrections rather than generic advice +- Use related skills to understand naming, boundaries, and overlap when they are relevant +- If optimizing an existing skill, treat the current skill and its support files as the source of truth before changing anything + +#### Design The Skill + +- Keep the skill to one coherent reusable job; narrow broad requests to the most reusable unit +- Prefer the smallest correct shape: start with `SKILL.md`, then add support files only when they materially help +- Derive `` by preferring `` when it is valid; otherwise create a lowercase hyphenated name that matches the intended folder name and satisfies the Agent Skills naming rules +- Store the target directory as `` = `/` +- Write the `description` as an imperative trigger instruction focused on user intent, such as `Use this skill when...` +- Prefer one clear default approach; mention alternatives only as explicit escape hatches +- Include gotchas, validation loops, examples, or output templates only when they materially improve execution +- Keep `SKILL.md` concise; move heavy detail to `references/`, `scripts/`, `assets/`, or `evals/` with explicit load conditions + +#### Write The Skill + +- Create or update `/SKILL.md` +- Keep frontmatter minimal: use `name` and `description`, and add optional fields only when they are justified +- Write concrete procedures and defaults instead of generic declarations +- Avoid empty directories, placeholder files, and speculative assets +- Store the changed file list as `` with one bullet per file path + +#### Validate The Skill + +- Confirm the directory name matches the skill name in frontmatter +- Confirm the frontmatter is valid and the description remains within the Agent Skills limits +- Confirm file references are relative to the skill root and point to real files +- If scripts or eval helpers were added or updated, run the most relevant available validation for those files +- Store the resulting validation summary as `` + +### Output + +If skill direction is missing, display: +``` +Skill direction required + +Provide the skill goal, workflow, or domain so the skill can be created. + +No additional steps are required. +``` + +If an existing skill already covers the scope, display: +``` +Skill already exists for this scope + +Existing skill: +Reason: + +No additional steps are required. +``` + +When the skill is created, display: +``` +Created skill: + +Path: /SKILL.md +Files: + + +Validation: + + +No additional steps are required. +``` diff --git a/packages/opencode/.opencode/commands/skill/optimize.md b/packages/opencode/.opencode/commands/skill/optimize.md new file mode 100644 index 0000000..5a48653 --- /dev/null +++ b/packages/opencode/.opencode/commands/skill/optimize.md @@ -0,0 +1,122 @@ +--- +description: Improve an existing Agent Skill from real feedback +agent: worker +--- + +## Goal + +Improve an existing Agent Skill so it triggers more reliably, stays lean, and produces better outputs for the intended workflow. + +## Additional Context + +- Favor targeted iteration over full rewrites; keep what already works and change only the parts blocking activation or execution quality +- Prefer optimization grounded in real prompts, evals, reviewer feedback, transcripts, or repeated failures over speculative cleanup + +## Workflow + +### Arguments + + +$ARGUMENTS + + +### Interpret Arguments + +- If `` contains a skill path, folder, slug, or `SKILL.md` reference, store it as `` +- If `` includes an optimization focus such as triggering, output quality, evals, or excess complexity, store it as `` +- If `` includes evidence such as prompts, failing cases, reviewer feedback, transcripts, or related files, store it as `` +- If `` includes constraints, audience, tools, or notes, store them as `` +- If `` is still missing, derive it from the conversation +- If the target skill still cannot be determined, STOP and report that a skill reference is required + +### Load Skill Context + +- Resolve `` to the target skill directory and store it as `` +- Confirm `/SKILL.md` exists; if not, STOP and report that the skill could not be found +- Read the current `SKILL.md` +- Read only the support files that materially affect the optimization focus, such as `references/`, `scripts/`, `assets/`, `evals/`, or nearby docs +- If optimization evidence was provided through ``, load and use it as source context + +### Reapply Skill Workflow + +- Identify the smallest set of changes that will improve `` without rewriting working parts of the skill +- If the skill already matches the requested focus and no meaningful improvement is justified, STOP and report that no changes are needed + +### Shared Skill Workflow + +#### Load Related Context + +- Read only the code, skills, scripts, docs, evals, and conversation context that materially affect this skill +- Ground decisions in project-specific patterns, successful examples, and repeated corrections rather than generic advice +- Use related skills to understand naming, boundaries, and overlap when they are relevant +- If optimizing an existing skill, treat the current skill and its support files as the source of truth before changing anything + +#### Design The Skill + +- Keep the skill to one coherent reusable job; narrow broad requests to the most reusable unit +- Prefer the smallest correct shape: start with `SKILL.md`, then add support files only when they materially help +- Preserve the existing skill name and directory unless the user explicitly asked for a rename or move +- Store the working skill name as `` and keep `` as the target directory +- Write the `description` as an imperative trigger instruction focused on user intent, such as `Use this skill when...` +- Prefer one clear default approach; mention alternatives only as explicit escape hatches +- Include gotchas, validation loops, examples, or output templates only when they materially improve execution +- Keep `SKILL.md` concise; move heavy detail to `references/`, `scripts/`, `assets/`, or `evals/` with explicit load conditions + +#### Write The Skill + +- Create or update `/SKILL.md` +- Keep frontmatter minimal: use `name` and `description`, and add optional fields only when they are justified +- Write concrete procedures and defaults instead of generic declarations +- Avoid empty directories, placeholder files, and speculative assets +- Store the changed file list as `` with one bullet per file path + +#### Validate The Skill + +- Confirm the directory name matches the skill name in frontmatter +- Confirm the frontmatter is valid and the description remains within the Agent Skills limits +- Confirm file references are relative to the skill root and point to real files +- If scripts or eval helpers were added or updated, run the most relevant available validation for those files +- Store the resulting validation summary as `` + +### Output + +If the target skill cannot be determined, display: +``` +Skill reference required + +Provide the skill path, folder, slug, or `SKILL.md` target to optimize. + +No additional steps are required. +``` + +If the target skill cannot be found, display: +``` +Skill not found + +Target: + +No additional steps are required. +``` + +If no meaningful optimization is needed, display: +``` +No skill changes needed + +Skill: +Reason: + +No additional steps are required. +``` + +When the skill is optimized, display: +``` +Optimized skill: + +Updated files: + + +Validation: + + +No additional steps are required. +``` diff --git a/packages/opencode/.opencode/kompass.jsonc b/packages/opencode/.opencode/kompass.jsonc index f24c886..624904a 100644 --- a/packages/opencode/.opencode/kompass.jsonc +++ b/packages/opencode/.opencode/kompass.jsonc @@ -40,6 +40,12 @@ "review": { "enabled": true }, + "skill/create": { + "enabled": true + }, + "skill/optimize": { + "enabled": true + }, "ship": { "enabled": true }, diff --git a/packages/opencode/kompass.jsonc b/packages/opencode/kompass.jsonc index 8b8a333..664c0df 100644 --- a/packages/opencode/kompass.jsonc +++ b/packages/opencode/kompass.jsonc @@ -22,6 +22,8 @@ "pr/fix": { "enabled": true }, "pr/review": { "enabled": true }, "review": { "enabled": true }, + "skill/create": { "enabled": true }, + "skill/optimize": { "enabled": true }, "ship": { "enabled": true }, "rmslop": { "enabled": true }, "todo": { "enabled": true }, @@ -55,6 +57,7 @@ "dev-flow": { "enabled": true }, "load-pr": { "enabled": true }, "load-ticket": { "enabled": true }, + "skill-authoring": { "enabled": true }, "summarize-changes": { "enabled": true }, }, diff --git a/packages/opencode/test/commands-config.test.ts b/packages/opencode/test/commands-config.test.ts index 6757a7f..5f8a046 100644 --- a/packages/opencode/test/commands-config.test.ts +++ b/packages/opencode/test/commands-config.test.ts @@ -38,6 +38,8 @@ describe("applyCommandsConfig", () => { "pr/create", "pr/review", "pr/fix", + "skill/create", + "skill/optimize", "ship", "ticket/ask", "ticket/create", @@ -64,6 +66,8 @@ describe("applyCommandsConfig", () => { assert.equal(cfg.command!["merge"]?.agent, "worker"); assert.equal(cfg.command!["pr/create"]?.agent, "worker"); assert.equal(cfg.command!["ticket/create"]?.agent, "worker"); + assert.equal(cfg.command!["skill/create"]?.agent, "worker"); + assert.equal(cfg.command!["skill/optimize"]?.agent, "worker"); assert.equal(cfg.command!["ticket/plan"]?.agent, "planner"); assert.equal(cfg.command!["ticket/plan-and-sync"]?.agent, "planner"); assert.equal(cfg.command!["ask"]?.agent, "worker"); @@ -420,6 +424,8 @@ describe("applyCommandsConfig", () => { assert.ok(cfg.command!["ticket/plan"]?.template); assert.ok(cfg.command!["ticket/plan-and-sync"]?.template); assert.ok(cfg.command!["pr/fix"]?.template); + assert.ok(cfg.command!["skill/create"]?.template); + assert.ok(cfg.command!["skill/optimize"]?.template); assert.ok(cfg.command!["ship"]?.template); assert.ok(cfg.command!["ticket/dev"]?.template); assert.ok(cfg.command!["review"]?.template); @@ -503,6 +509,30 @@ describe("applyCommandsConfig", () => { assert.doesNotMatch(ticketCreateTemplate, /<%/); }); + test("embeds shared skill-authoring guidance in skill commands", async () => { + delete process.env.CI; + const cfg: { command?: Record } = {}; + + await applyCommandsConfig(cfg as never, process.cwd()); + + assert.ok(cfg.command); + const skillCreateTemplate = cfg.command!["skill/create"].template; + const skillOptimizeTemplate = cfg.command!["skill/optimize"].template; + + assert.match(skillCreateTemplate, /## Goal/); + assert.match(skillCreateTemplate, /Shared Skill Workflow/); + assert.match(skillCreateTemplate, /Load Related Context/); + assert.match(skillCreateTemplate, /Ground decisions in project-specific patterns/); + assert.doesNotMatch(skillCreateTemplate, /<%/); + + assert.match(skillOptimizeTemplate, /## Goal/); + assert.match(skillOptimizeTemplate, /Improve an existing Agent Skill/); + assert.match(skillOptimizeTemplate, /Shared Skill Workflow/); + assert.match(skillOptimizeTemplate, /Reapply Skill Workflow/); + assert.match(skillOptimizeTemplate, /Identify the smallest set of changes/); + assert.doesNotMatch(skillOptimizeTemplate, /<%/); + }); + test("embeds all expected components in ticket/dev command", async () => { delete process.env.CI; const cfg: { command?: Record } = {}; diff --git a/packages/web/src/components/CommandShowcase.astro b/packages/web/src/components/CommandShowcase.astro index 64979c3..d940a9e 100644 --- a/packages/web/src/components/CommandShowcase.astro +++ b/packages/web/src/components/CommandShowcase.astro @@ -20,7 +20,7 @@ interface CommandScenario { command: string; agentName: string; task: string; - group: 'core' | 'ticket' | 'pr' | 'orchestration'; + group: 'workflow' | 'guidelines' | 'ticket' | 'pr' | 'orchestration'; steps: SessionStep[]; } @@ -31,7 +31,7 @@ const scenarios: CommandScenario[] = [ command: '/ask is this project cool?', agentName: 'Worker', task: 'Answer questions about the current project or code', - group: 'core', + group: 'workflow', steps: [ { id: 'thinking', phase: 'thinking', content: 'Need just enough repository context to answer the question directly.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -51,7 +51,7 @@ const scenarios: CommandScenario[] = [ command: '/branch docs cleanup', agentName: 'Worker', task: 'Create a categorized branch from current work', - group: 'core', + group: 'workflow', steps: [ { id: 'thinking', phase: 'thinking', content: 'Summarize uncommitted work, check whether the current branch already looks like a work branch, then generate a short categorized name.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -70,7 +70,7 @@ const scenarios: CommandScenario[] = [ command: '/commit tighten command docs', agentName: 'Worker', task: 'Create a commit from uncommitted work', - group: 'core', + group: 'workflow', steps: [ { id: 'thinking', phase: 'thinking', content: 'Load uncommitted changes, stop if there is nothing to commit, then stage the work and write a conventional message.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -90,7 +90,7 @@ const scenarios: CommandScenario[] = [ command: '/commit-and-push', agentName: 'Worker', task: 'Create a commit and push it', - group: 'core', + group: 'workflow', steps: [ { id: 'thinking', phase: 'thinking', content: 'Create the commit from current uncommitted work, then push and fall back to upstream setup if needed.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -110,7 +110,7 @@ const scenarios: CommandScenario[] = [ command: '/learn docs', agentName: 'Worker', task: 'Document non-obvious session learnings', - group: 'core', + group: 'guidelines', steps: [ { id: 'thinking', phase: 'thinking', content: 'Review the session for durable, non-obvious learnings and place them in the narrowest useful AGENTS.md scope.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -123,13 +123,57 @@ const scenarios: CommandScenario[] = [ ] } ] }, + { + id: 'skill-create', + label: '/skill/create', + command: '/skill/create add a release-notes skill', + agentName: 'Worker', + task: 'Create a new skill from project context', + group: 'guidelines', + steps: [ + { id: 'thinking', phase: 'thinking', content: 'Inspect existing skill conventions, narrow the scope to one reusable workflow, then author the smallest useful skill file set.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'glob', args: '.agents/skills/**/SKILL.md', status: 'complete' }, + { tool: 'read', args: 'related docs and examples', status: 'complete' }, + { tool: 'apply_patch', args: 'create .agents/skills/release-notes/SKILL.md', status: 'complete' }, + { tool: 'read', args: 're-check structure and references', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Created skill: release-notes', + 'Path: .agents/skills/release-notes/SKILL.md', + 'Validation: structure and references checked' + ] } + ] + }, + { + id: 'skill-optimize', + label: '/skill/optimize', + command: '/skill/optimize .agents/skills/frontend-skill trigger coverage', + agentName: 'Worker', + task: 'Improve an existing skill from grounded feedback', + group: 'guidelines', + steps: [ + { id: 'thinking', phase: 'thinking', content: 'Load the target skill, identify the weakest parts of the trigger or instructions, then make the smallest improvements that improve activation or output quality.' }, + { id: 'tools', phase: 'tool_calls', toolCalls: [ + { tool: 'read', args: '.agents/skills/frontend-skill/SKILL.md', status: 'complete' }, + { tool: 'read', args: 'related examples and support files', status: 'complete' }, + { tool: 'apply_patch', args: 'tighten description and core guidance', status: 'complete' }, + { tool: 'read', args: 're-check skill files and references', status: 'complete' } + ] }, + { id: 'output', phase: 'output', output: [ + 'Optimized skill: .agents/skills/frontend-skill', + 'Updated files: SKILL.md', + 'Validation: structure and references checked' + ] } + ] + }, { id: 'merge', label: '/merge', command: '/merge origin/main', agentName: 'Worker', task: 'Merge another branch into the current branch', - group: 'core', + group: 'workflow', steps: [ { id: 'thinking', phase: 'thinking', content: 'Confirm the working tree is clean, resolve the merge source, run the merge, and only continue if conflicts can be resolved confidently.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -148,7 +192,7 @@ const scenarios: CommandScenario[] = [ command: '/rmslop main', agentName: 'Worker', task: 'Clean AI-style slop from branch changes', - group: 'core', + group: 'workflow', steps: [ { id: 'thinking', phase: 'thinking', content: 'Load the branch diff, identify noisy or inconsistent AI-shaped edits, clean them up, validate, and commit the cleanup.' }, { id: 'tools', phase: 'tool_calls', toolCalls: [ @@ -417,7 +461,8 @@ const scenarios: CommandScenario[] = [ ]; // Group scenarios -const coreScenarios = scenarios.filter(s => s.group === 'core'); +const workflowScenarios = scenarios.filter(s => s.group === 'workflow'); +const guidelineScenarios = scenarios.filter(s => s.group === 'guidelines'); const ticketScenarios = scenarios.filter(s => s.group === 'ticket'); const prScenarios = scenarios.filter(s => s.group === 'pr'); const orchestrationScenarios = scenarios.filter(s => s.group === 'orchestration'); @@ -434,13 +479,13 @@ const orchestrationScenarios = scenarios.filter(s => s.group === 'orchestration'
- +
- Core + Workflow
- {coreScenarios.map((scenario, index) => ( + {workflowScenarios.map((scenario, index) => (
+ +
+ Guidelines +
+ {guidelineScenarios.map((scenario) => ( + + ))} +
+
Ticket @@ -940,6 +1004,11 @@ const orchestrationScenarios = scenarios.filter(s => s.group === 'orchestration' background: rgba(139, 92, 246, 0.1); } + .command-group--guidelines { + border-color: rgba(248, 184, 78, 0.25); + background: rgba(248, 184, 78, 0.1); + } + .command-group--pr { border-color: rgba(34, 197, 94, 0.25); background: rgba(34, 197, 94, 0.1); @@ -966,6 +1035,11 @@ const orchestrationScenarios = scenarios.filter(s => s.group === 'orchestration' background: rgba(139, 92, 246, 0.2); } + .command-group--guidelines .command-group__legend { + color: rgba(248, 184, 78, 0.95); + background: rgba(248, 184, 78, 0.2); + } + .command-group--pr .command-group__legend { color: rgba(34, 197, 94, 0.9); background: rgba(34, 197, 94, 0.2); @@ -1016,6 +1090,11 @@ const orchestrationScenarios = scenarios.filter(s => s.group === 'orchestration' background: rgba(139, 92, 246, 0.1); } + .command-tab--guidelines { + border-color: rgba(248, 184, 78, 0.25); + background: rgba(248, 184, 78, 0.1); + } + .command-tab--ticket:hover, .command-tab--ticket.is-active { border-color: rgba(139, 92, 246, 0.45); @@ -1023,6 +1102,13 @@ const orchestrationScenarios = scenarios.filter(s => s.group === 'orchestration' color: var(--text); } + .command-tab--guidelines:hover, + .command-tab--guidelines.is-active { + border-color: rgba(248, 184, 78, 0.45); + background: rgba(248, 184, 78, 0.18); + color: var(--text); + } + .command-tab--pr { border-color: rgba(34, 197, 94, 0.25); background: rgba(34, 197, 94, 0.1); diff --git a/packages/web/src/content/docs/docs/getting-started.mdx b/packages/web/src/content/docs/docs/getting-started.mdx index b99685f..2b0faf2 100644 --- a/packages/web/src/content/docs/docs/getting-started.mdx +++ b/packages/web/src/content/docs/docs/getting-started.mdx @@ -54,6 +54,8 @@ Once the plugin is installed, you can use commands such as: - `/ask` - `/dev` - `/review` +- `/skill/create` +- `/skill/optimize` - `/ticket/plan` - `/pr/create` - `/ship` diff --git a/packages/web/src/content/docs/docs/reference/commands/index.mdx b/packages/web/src/content/docs/docs/reference/commands/index.mdx index 0eea5d9..396c2a2 100644 --- a/packages/web/src/content/docs/docs/reference/commands/index.mdx +++ b/packages/web/src/content/docs/docs/reference/commands/index.mdx @@ -7,7 +7,8 @@ Kompass ships workflow-oriented commands authored as explicit templates in `pack ## Groups -- Core: `/ask`, `/branch`, `/commit`, `/commit-and-push`, `/learn`, `/merge`, `/rmslop` +- Workflow: `/ask`, `/branch`, `/commit`, `/commit-and-push`, `/merge`, `/rmslop` +- Guidelines: `/learn`, `/skill/create`, `/skill/optimize` - Ticket: `/ticket/ask`, `/ticket/create`, `/ticket/dev`, `/ticket/plan`, `/ticket/plan-and-sync` - PR: `/pr/create`, `/pr/fix`, `/pr/review`, `/review` - Orchestration: `/dev`, `/ship`, `/todo` @@ -19,7 +20,7 @@ Kompass ships workflow-oriented commands authored as explicit templates in `pack - navigator workflows orchestrate locally and delegate focused leaf work with literal `` blocks - outputs are deterministic, reviewable, and usually terminal -## Core workflows +## Workflow Commands ### `/ask` @@ -53,14 +54,6 @@ Creates a commit and immediately pushes it to the remote repository. - arguments: optional commit message guidance - expected tools: `changes_load(uncommitted)`, git commit, `git push` with upstream fallback when needed -### `/learn` - -Extracts non-obvious learnings from the current session and documents them into the right `AGENTS.md` scope. - -- usage: `/learn [focus]` -- arguments: optional focus scope or extra guidance -- expected tools: `read`, file edit tools - ### `/merge` Merges a provided branch into the current branch, defaulting to the repo base branch, and resolves conflicts with a best-effort preference for the incoming branch. @@ -77,6 +70,32 @@ Removes AI-generated code slop and inconsistencies from branch changes. - arguments: optional base branch or cleanup guidance - expected tools: `changes_load`, file-edit tools, validation commands, commit git commands +## Guidelines Commands + +### `/learn` + +Extracts non-obvious learnings from the current session and documents them into the right `AGENTS.md` scope. + +- usage: `/learn [focus]` +- arguments: optional focus scope or extra guidance +- expected tools: `read`, file edit tools + +### `/skill/create` + +Creates a focused Agent Skill from repository context and user direction. + +- usage: `/skill/create [skill-direction]` +- arguments: optional skill request, desired name, supporting sources, or constraints; auto-derives from the conversation when omitted +- expected tools: `glob`, `read`, file-edit tools, and relevant validation commands + +### `/skill/optimize` + +Improves an existing Agent Skill using real prompts, failures, evals, or other grounded feedback. + +- usage: `/skill/optimize [skill-and-focus]` +- arguments: optional skill path or slug, optimization focus, supporting evidence, or constraints; auto-derives from the conversation when omitted +- expected tools: `read`, `glob`, file-edit tools, and relevant validation commands + ## Ticket workflows ### `/ticket/ask` diff --git a/packages/web/src/content/docs/docs/reference/commands/skill-create.mdx b/packages/web/src/content/docs/docs/reference/commands/skill-create.mdx new file mode 100644 index 0000000..38328e4 --- /dev/null +++ b/packages/web/src/content/docs/docs/reference/commands/skill-create.mdx @@ -0,0 +1,30 @@ +--- +title: /skill/create +description: Create a focused Agent Skill from repository context and user direction. +--- + +## Purpose + +Use `/skill/create` to author a new reusable Agent Skill that is grounded in the current project instead of generic best-practice filler. + +## Usage + +```text +/skill/create [skill-direction] +``` + +## Typical flow + +- inspect existing skills, skill roots, and nearby project artifacts +- stop if the request would duplicate an existing skill without a clear scope boundary +- derive a valid hyphenated skill name and default root such as `.agents/skills/` +- create a concise `SKILL.md` with an intent-oriented trigger description and focused execution guidance +- add `references/`, `scripts/`, or `assets/` only when they materially improve the skill +- validate the structure, frontmatter, trigger description, and references + +## Common tools + +- `glob` +- `read` +- file edit tools +- relevant validation commands when they exist diff --git a/packages/web/src/content/docs/docs/reference/commands/skill-optimize.mdx b/packages/web/src/content/docs/docs/reference/commands/skill-optimize.mdx new file mode 100644 index 0000000..d2cfd75 --- /dev/null +++ b/packages/web/src/content/docs/docs/reference/commands/skill-optimize.mdx @@ -0,0 +1,30 @@ +--- +title: /skill/optimize +description: Improve an existing Agent Skill using real prompts, failures, evals, or other grounded feedback. +--- + +## Purpose + +Use `/skill/optimize` to load an existing skill, identify the weakest parts, and then reapply the same shared skill workflow used by `/skill/create`. + +## Usage + +```text +/skill/optimize [skill-and-focus] +``` + +## Typical flow + +- resolve the target skill from a path, slug, or `SKILL.md` reference +- load the current skill plus only the support files and evidence relevant to the optimization focus +- decide whether a meaningful improvement is actually needed +- reapply the shared skill workflow to improve the skill without rewriting working parts blindly +- update support files only when they materially help +- validate the resulting skill structure, frontmatter, trigger description, and references + +## Common tools + +- `glob` +- `read` +- file edit tools +- relevant validation commands when they exist diff --git a/packages/web/src/content/docs/docs/reference/components/index.mdx b/packages/web/src/content/docs/docs/reference/components/index.mdx index 043fdc1..b756ad4 100644 --- a/packages/web/src/content/docs/docs/reference/components/index.mdx +++ b/packages/web/src/content/docs/docs/reference/components/index.mdx @@ -13,6 +13,7 @@ Bundled components: - `dev-flow` - `load-pr` - `load-ticket` +- `skill-authoring` - `summarize-changes` ## Bundled components @@ -41,6 +42,10 @@ Loads PR context through `pr_load` and treats returned discussion, review histor Loads ticket context through `ticket_load`, with optional comments, and treats returned discussion and relevant attachments as source context. +### `skill-authoring` + +Provides the shared authoring rules for skill-focused commands, including scope, trigger-description quality, progressive disclosure, and validation expectations. + ### `summarize-changes` Guides commands to inspect comparison metadata, commit history, and changed files before grouping the work into themes. diff --git a/packages/web/src/content/docs/docs/reference/components/skill-authoring.mdx b/packages/web/src/content/docs/docs/reference/components/skill-authoring.mdx new file mode 100644 index 0000000..3e84b0d --- /dev/null +++ b/packages/web/src/content/docs/docs/reference/components/skill-authoring.mdx @@ -0,0 +1,11 @@ +--- +title: skill-authoring +description: Shared guidance block for creating and improving Agent Skills. +--- + +## Behavior + +- loads only the related code, skills, docs, evals, and conversation context needed to understand the skill well +- designs the skill as one coherent reusable job with a clear trigger description and sensible defaults +- writes or updates `SKILL.md` concisely, adding support files only when they materially help +- validates naming, frontmatter, file references, and relevant scripts or eval helpers diff --git a/packages/web/src/pages/index.astro b/packages/web/src/pages/index.astro index bd5471d..1d1acc9 100644 --- a/packages/web/src/pages/index.astro +++ b/packages/web/src/pages/index.astro @@ -16,7 +16,7 @@ const heroHighlights = [ }, { eyebrow: "Integrations", - title: "GitHub workflows, tickets, PRs, review loops" + title: "Skills, tickets, PRs, review loops" } ];