@yemi33/minions 0.1.1563 → 0.1.1564

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1564 (2026-04-27)
+
+### Other
+- Harden skill creation guidance
+
 ## 0.1.1563 (2026-04-27)
 
 ### Fixes

package/README.md

@@ -457,7 +457,7 @@ All playbooks use `{{template_variables}}` filled from project config. Condition
 
 Every playbook has an explicit "When to Stop" section telling agents exactly what constitutes completion. Code-pushing playbooks enforce **build → test → repo checks → push** ordering. Per-type max-turns prevent runaway tool loops (explore=30, ask=20, implement=75, verify=100).
 
-Playbooks are fully customizable — edit them to match your workflow. System prompts for CC and plan advisor live in `prompts/` with `{{variable}}` substitution.
+Playbooks are fully customizable — edit the shared templates in `playbooks/` to change the repo-wide defaults. You can also create machine-local overrides in `projects/<name>/playbooks/<type>.md`; Minions will prefer those for that project, but they are treated as user data and remain gitignored. System prompts for CC and plan advisor live in `prompts/` with `{{variable}}` substitution.
 
 ## Health Monitoring
 
@@ -503,7 +503,7 @@ When a reviewer flags issues, the engine creates `feedback-<author>-from-<review
 `engine/metrics.json` tracks per agent: tasks completed, errors, PRs created/approved/rejected, reviews done. Visible in CLI (`status`) and dashboard with color-coded approval rates.
 
 ### 5. Skills
-Agents save repeatable workflows to `skills/<name>.md` with Claude Code-compatible frontmatter. Engine builds an index injected into all prompts. Skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in the dashboard Skills section.
+Agents save Minions-wide repeatable workflows as user-level Claude skills in `~/.claude/skills/<name>/SKILL.md`, so they are usable both inside Minions and in normal Claude windows. Repo-specific skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in the dashboard Skills section.
 
 See `docs/self-improvement.md` for the full breakdown.
 
@@ -730,5 +730,3 @@ Per-project engine state remains centralized:
     work-items.json      <- Per-project work queue
     pull-requests.json   <- PR tracker
 ```
-
-

package/docs/self-improvement.md

@@ -257,14 +257,14 @@ Metrics are currently informational — displayed in status and dashboard. Plann
 
 When an agent discovers a repeatable multi-step procedure, it can save it as a **skill** — a structured, reusable workflow compatible with Claude Code's skill system. Skills are stored in two locations:
 
-- **Minions-wide:** `~/.minions/skills/<name>.md` — shared across all agents, no PR required
+- **Minions-wide:** `~/.claude/skills/<name>/SKILL.md` — user-level Claude skill, shared across Minions and normal Claude windows, no PR required
 - **Project-specific:** `<project>/.claude/skills/<name>/SKILL.md` — scoped to one repo, requires a PR
 
 ### Flow
 
 ```
 Agent discovers repeatable pattern during task
-  → writes skills/<name>.md with frontmatter (name, description, trigger, allowed-tools)
+  → writes ~/.claude/skills/<name>/SKILL.md with frontmatter (name, description, trigger, allowed-tools)
   → engine detects new skill files on next tick
   → builds skill index (name + trigger + file path)
   → index injected into every agent's system prompt
@@ -314,10 +314,11 @@ When a git merge or rebase produces conflicts in yarn.lock.
 
 ### When agents should create skills
 
-- Multi-step procedures they had to figure out (build setup, deployment, migration)
-- Error recovery patterns (how to fix a specific class of failure)
-- Project-specific workflows that aren't documented elsewhere
-- Cross-repo coordination steps
+- Only when the workflow is durable, multi-step, and likely to be reused on future tasks
+- Only when the workflow is not already documented in repo docs, notes, playbooks, or existing skills
+- Good candidates: build setup, deployment, migrations, recurring error-recovery patterns, cross-repo coordination steps
+- Prefer zero skills over a weak skill; one-off findings and task-specific notes belong in inbox notes or `notes.md`
+- Do not create skills for isolated fixes, obvious repository facts, or instructions already covered elsewhere
 
 ## Configuration
 

package/engine/playbook.js

@@ -362,14 +362,15 @@ function renderPlaybook(type, vars) {
   content += `- Conventions to follow\n`;
   content += `- **SOURCE REFERENCES for every finding** — file paths with line numbers, PR URLs, API endpoints, config keys. Format: \`(source: path/to/file.ts:42)\` or \`(source: PR-12345)\`. Without references, findings cannot be verified.\n\n`;
   content += `### Skill Extraction (IMPORTANT)\n\n`;
-  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — output it as a fenced skill block. The engine will automatically extract it.\n\n`;
+  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — only output it as a fenced skill block when **all** of these are true: (1) you had to discover it during this task, (2) it is not already captured in team memory, repo docs, existing playbooks, or existing skills, and (3) another agent is likely to reuse it on future tasks. **Zero skills is the default.** Prefer the inbox findings for one-off notes, repo facts, and task-specific observations.\n\n`;
   content += `Format your skill as a fenced code block with the \`skill\` language tag:\n\n`;
   content += '````\n```skill\n';
   content += `---\nname: short-descriptive-name\ndescription: One-line description of what this skill does\nallowed-tools: Bash, Read, Edit\ntrigger: when should an agent use this\nscope: minions\nproject: any\n---\n\n# Skill Title\n\n## Steps\n1. ...\n2. ...\n\n## Notes\n...\n`;
   content += '```\n````\n\n';
-  content += `- Set \`scope: minions\` for cross-project skills (engine writes to ~/.claude/skills/ automatically)\n`;
-  content += `- Set \`scope: project\` + \`project: <name>\` for repo-specific skills (engine queues a PR to <project>/.claude/skills/)\n`;
-  content += `- Only output a skill block if you genuinely discovered something reusable — don't force it\n`;
+  content += `- Set \`scope: minions\` for cross-project or Minions-wide skills; the engine writes them to ~/.claude/skills/ so they are available in normal Claude windows too\n`;
+  content += `- Set \`scope: project\` + \`project: <name>\` only for repo-specific skills; the engine queues a PR to <project>/.claude/skills/\n`;
+  content += `- Emit at most one skill block per task unless you uncovered two clearly distinct reusable workflows\n`;
+  content += `- Do NOT create a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs/playbooks/skills\n`;
 
   // Inject project-level variables from config
   const config = getConfig();
@@ -471,7 +472,7 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
   prompt += `4. Write learnings to the path specified in the task prompt (format: \`notes/inbox/{agent}-{work-item-id}-{date}-{time}.md\`)\n`;
   prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n`;
-  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — the engine auto-extracts it to ~/.claude/skills/\n\n`;
+  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — minions-scoped skills are auto-extracted to ~/.claude/skills/ so they are available in normal Claude windows too\n\n`;
 
   return prompt;
 }
@@ -504,7 +505,7 @@ function buildAgentContext(agentId, config, project) {
 
   // KB and skills: NOT injected — agents can Glob/Read when needed
   // This saves ~27KB per dispatch. Reference note so agents know they exist:
-  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. Skills are in \`skills/*.md\` and \`.claude/skills/\`. Use Glob/Read to browse when relevant.\n\n`;
+  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. User-level Minions skills live in \`~/.claude/skills/\`, and project-specific skills live in \`<project>/.claude/skills/\`. Use Glob/Read when relevant.\n\n`;
 
   // Minions awareness: what's in flight, who's doing what
   const dispatch = getDispatch();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1563",
+  "version": "0.1.1564",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/explore.md

@@ -60,7 +60,7 @@ Use subagents only for genuinely parallel, independent tasks. For reading files,
 - Use the appropriate MCP tools for PR creation — check available tools before starting.
 - Do NOT checkout branches in the main working tree — use worktrees.
 - Read `notes.md` for all team rules before starting.
-- If you discover a repeatable workflow, output it as a ```skill block (the engine auto-extracts it to ~/.claude/skills/)
+- Only emit a ```skill block if you uncovered a durable reusable workflow that is not already documented and is likely to help future tasks; zero skills is the default, and one-off findings belong in the inbox notes instead.
 
 ## When to Stop
 

package/playbooks/shared-rules.md

@@ -33,7 +33,7 @@ Your context window may be compacted or summarized mid-task by Claude's automati
   5. Previous agent output in `agents/*/live-output.log` for related tasks
   6. Work item descriptions and `resultSummary` for prior completed work on the same topic
   Only after exhausting team memory should you look outside (web search, codebase exploration, external docs). This avoids duplicating research another agent already completed and ensures team decisions are respected.
-- If you discover a repeatable workflow, output it as a fenced skill block. The engine auto-extracts it to `~/.claude/skills/<name>/SKILL.md`. Required format:
+- Only output a fenced skill block when **all** of these are true: (1) you discovered a durable multi-step workflow that was not already documented in team memory, repo docs, existing playbooks, or existing skills, (2) another agent is likely to need it on future tasks, and (3) the workflow is specific enough to be actionable but general enough to stand alone. **Zero skills is the default.** Prefer writing one-off findings, repo facts, or task-specific notes to the inbox findings instead of creating a skill. Emit **at most one skill block per task** unless the task clearly uncovered two unrelated reusable workflows. The engine auto-extracts valid skill blocks to `~/.claude/skills/<name>/SKILL.md`, so `scope: minions` skills become user-level Claude skills available in normal Claude windows too. Required format:
   ````
   ```skill
   ---
@@ -45,7 +45,8 @@ Your context window may be compacted or summarized mid-task by Claude's automati
   Instructions for the skill go here.
   ```
   ````
-  The `name` and `description` fields are required. `scope` defaults to `minions` (global). Use `scope: project` + `project: ProjectName` for project-specific skills.
+  The `name` and `description` fields are required. `scope` defaults to `minions` (global). Use `scope: minions` for user-level reusable skills; use `scope: project` + `project: ProjectName` only for repo-specific skills that should land in that project via PR.
+  Do **not** create a skill for one-off bug fixes, isolated command outputs, obvious repo facts, or anything already covered by existing docs/playbooks/skills.
 - Do TDD where it makes sense — write failing tests first, then implement, then verify tests pass. Especially for bug fixes (write a test that reproduces the bug) and new utility functions.
 
 ## Checking PR and Build Status