@yemi33/minions 0.1.1959 → 0.1.1960

package/docs/skills.md

@@ -0,0 +1,43 @@
+# Skill Block Format
+
+Agents emit a fenced `skill` block when they discover a durable, reusable workflow that future agents are likely to need. See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the eligibility threshold and the "zero skills is the default" rule.
+
+The engine extracts valid blocks from agent stdout and from inbox findings (`notes/inbox/*.md`) and writes them into the selected runtime's native personal skills directory (e.g. `~/.claude/skills/<name>/SKILL.md` for Claude, the equivalent personal skills directory for Copilot). Project-scoped skills are landed via PR into the matching project's playbook tree.
+
+## Block format
+
+````
+```skill
+---
+name: short-descriptive-name
+description: One-line description of when to trigger this skill
+scope: minions
+---
+
+# Skill Title
+
+## Steps
+1. ...
+2. ...
+
+## Notes
+...
+```
+````
+
+### Frontmatter fields
+
+- `name` (**required**) — kebab-case identifier; becomes the on-disk directory name.
+- `description` (**required**) — one-line "when to use this" hint shown in skill listings.
+- `scope` — `minions` (default; user-level skill, available in any runtime window) or `project` (repo-local skill, landed via PR into that project).
+- `project` — required when `scope: project`; the project name the skill belongs to.
+- `allowed-tools` (optional) — comma-separated tools the skill is permitted to call (e.g. `Bash, Read, Edit`).
+- `trigger` (optional) — natural-language phrase describing when an agent should invoke the skill.
+
+### Body
+
+Plain Markdown. Include the steps, commands, file paths, and notes another agent needs to follow the workflow without reading the original task context. Cite source files and PR numbers where useful — the body is what future agents actually read.
+
+## When not to emit a skill
+
+See [`playbooks/shared-rules.md`](../playbooks/shared-rules.md) for the full threshold. In short: do not emit a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs, playbooks, or skills.

package/engine/playbook.js

@@ -488,16 +488,6 @@ function renderPlaybook(type, vars) {
   content += `- Gotchas or warnings for future agents\n`;
   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 — 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 or Minions-wide skills; the engine writes them to the selected runtime's native personal skills directory so they are available in normal runtime windows too\n`;
-  content += `- Set \`scope: project\` + \`project: <name>\` only for repo-specific skills; the engine queues a PR to the selected runtime's native project skills directory\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();
@@ -604,7 +594,7 @@ function buildSystemPrompt(agentId, config, project) {
   // Agent identity
   prompt += `# You are ${agent.name} (${agent.role})\n\n`;
   prompt += `Agent ID: ${agentId}\n`;
-  prompt += `Skills: ${(agent.skills || []).join(', ')}\n\n`;
+  prompt += `Expertise: ${(agent.skills || []).join(', ')}\n\n`;
 
   // Charter (detailed instructions — typically 1-2KB)
   if (charter) {
@@ -624,8 +614,7 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `2. ${getRepoHostToolRule(project)}\n`;
   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 — minions-scoped skills are auto-extracted to the selected runtime's native personal skills directory\n\n`;
+  prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n\n`;
 
   return prompt;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1959",
+  "version": "0.1.1960",
   "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,6 @@ Use subagents only for genuinely parallel, independent tasks. For reading files,
 - Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer the `az` CLI first and use ADO MCP only as a fallback when `az` is unavailable or insufficient.
 - Do NOT checkout branches in the main working tree — use worktrees.
 - Read `notes.md` for all team rules before starting.
-- 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

@@ -46,20 +46,7 @@ Bias toward senior-engineer restraint:
   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.
-- 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
-  ---
-  name: skill-name-here
-  description: One-line description of when to trigger this skill
-  scope: minions
-  ---
-
-  Instructions for the skill go here.
-  ```
-  ````
-  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.
+- 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 the selected runtime's native personal skills directory, so `scope: minions` skills become user-level Claude/Copilot skills available in normal runtime windows too. See [`docs/skills.md`](../docs/skills.md) for the skill block format. 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.
 - 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.
 
 ## Completion Reports