Add skill authoring commands

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.

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 },
   },
 

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,22 +233,25 @@
         "load-ticket": {
           "$ref": "#/$defs/componentConfig"
         },
+        "skill-authoring": {
+          "$ref": "#/$defs/componentConfig"
+        },
         "summarize-changes": {
           "$ref": "#/$defs/componentConfig"
         },
         "enabled": {
           "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
         },
         "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"

packages/core/commands/index.ts

@@ -68,6 +68,16 @@ export const commandDefinitions: Record<string, CommandDefinition> = {
     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",

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>
+$ARGUMENTS
+</arguments>
+
+### Interpret Arguments
+
+- If `<arguments>` contains a clear skill request, store it as `<skill-request>`
+- If `<arguments>` contains an explicit skill name, slug, or desired folder name, store it as `<requested-name>`
+- If `<arguments>` includes supporting context such as file paths, URLs, ticket references, or existing examples, store them as `<context-sources>`
+- If `<arguments>` includes constraints, audience, tools, or notes, store them as `<additional-context>`
+- If `<skill-request>` 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 `<skill-root>`
+- Otherwise, store `.agents/skills` as `<skill-root>`
+- 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: <existing-skill-path>
+Reason: <overlap-reason>
+
+No additional steps are required.
+```
+
+When the skill is created, display:
+```
+Created skill: <skill-name>
+
+Path: <skill-dir>/SKILL.md
+Files:
+<file-lines>
+
+Validation:
+<validation-results>
+
+No additional steps are required.
+```

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>
+$ARGUMENTS
+</arguments>
+
+### Interpret Arguments
+
+- If `<arguments>` contains a skill path, folder, slug, or `SKILL.md` reference, store it as `<skill-ref>`
+- If `<arguments>` includes an optimization focus such as triggering, output quality, evals, or excess complexity, store it as `<optimization-focus>`
+- If `<arguments>` includes evidence such as prompts, failing cases, reviewer feedback, transcripts, or related files, store it as `<optimization-inputs>`
+- If `<arguments>` includes constraints, audience, tools, or notes, store them as `<additional-context>`
+- If `<skill-ref>` 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 `<skill-ref>` to the target skill directory and store it as `<skill-dir>`
+- Confirm `<skill-dir>/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 `<optimization-inputs>`, load and use it as source context
+
+### Reapply Skill Workflow
+
+- Identify the smallest set of changes that will improve `<optimization-focus>` 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: <skill-ref>
+
+No additional steps are required.
+```
+
+If no meaningful optimization is needed, display:
+```
+No skill changes needed
+
+Skill: <skill-dir>
+Reason: <no-change-reason>
+
+No additional steps are required.
+```
+
+When the skill is optimized, display:
+```
+Optimized skill: <skill-dir>
+
+Updated files:
+<file-lines>
+
+Validation:
+<validation-results>
+
+No additional steps are required.
+```

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 `<skill-name>` by preferring `<requested-name>` 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 `<skill-dir>` = `<skill-root>/<skill-name>`
+<% } else { -%>
+- Preserve the existing skill name and directory unless the user explicitly asked for a rename or move
+- Store the working skill name as `<skill-name>` and keep `<skill-dir>` 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-dir>/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 `<file-lines>` 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 `<validation-results>`

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 },
   },
 

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<string, string>;
@@ -443,6 +449,7 @@ const defaultComponentPaths: Record<string, string> = {
   "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",
 };