Skip to content

m3taz-ahmed/aizee / skills/bmad-toolsmith

bmad-toolsmith

Verified

Smithy the Toolsmith builds and maintains BMad skills, agents and modules. Use when the user asks for Smithy or says "build a skill", "make an agent", "scaffold a skill", "turn my session logs into a skill", "fix this skill", "convert this prompt to a skill", "review this skill", "optimize this skill", "cut this skill down", "make this skill BMad compliant", "package a module", "validate my module" or "migrate my old module". Not for running evals (`bmad-eval`) or overriding an installed skill (`bmad-customize`).

FileKindSize
SKILL.mdskill md3.6 KB
approaches/eval-first.mdmarkdown1.3 KB
approaches/eval-loop.mdmarkdown2.4 KB
approaches/from-logs.mdmarkdown1.7 KB
approaches/lean.mdmarkdown1.7 KB
approaches/scaffold.mdmarkdown1.3 KB
approaches/skill-creator-loop.mdmarkdown1.2 KB
bmod.tomlconfig118 B
canon.mdmarkdown10.5 KB
customize.tomlconfig4.8 KB
discover.mdmarkdown5.5 KB
evals/triggers.jsonconfig3.3 KB
lenses/lens-architecture.mdmarkdown2.9 KB
lenses/lens-contract.mdmarkdown1.4 KB
lenses/lens-customization.mdmarkdown2.4 KB
lenses/lens-determinism.mdmarkdown1.8 KB
lenses/lens-leanness.mdmarkdown3.1 KB
lenses/lens-trigger.mdmarkdown2.4 KB
lenses/standards.mdmarkdown5.2 KB
modes/convert.mdmarkdown2.1 KB
modes/cut-roles.mdmarkdown3.3 KB
modes/cut.mdmarkdown3.3 KB
modes/edit.mdmarkdown1.3 KB
modes/migrate.mdmarkdown3.3 KB
modes/package.mdmarkdown2.6 KB
modes/review.mdmarkdown1.3 KB
modes/validate.mdmarkdown1.8 KB
scripts/count_tokens.pyscript3.6 KB
scripts/cut_check.pyscript5.1 KB
scripts/init_skill.pyscript13.3 KB
scripts/prepass.pyscript7.5 KB
scripts/process_template.pyscript4.8 KB
scripts/read_session_log.pyscript9.8 KB
scripts/registry.pyscript5.9 KB
scripts/scan_legacy_module.pyscript7.7 KB
scripts/scan_paths.pyscript9.2 KB
scripts/scan_scripts.pyscript6.6 KB
scripts/tests/test_count_tokens.pyscript4.1 KB
scripts/tests/test_cut_check.pyscript3.1 KB
scripts/tests/test_init_skill.pyscript9.7 KB
scripts/tests/test_memory_agent_scripts.pyscript8.6 KB
scripts/tests/test_prepass.pyscript8.3 KB
scripts/tests/test_process_template.pyscript4.7 KB
scripts/tests/test_read_session_log.pyscript7.3 KB
scripts/tests/test_registry.pyscript6.0 KB
scripts/tests/test_scan_legacy_module.pyscript8.2 KB
scripts/tests/test_scan_paths.pyscript7.7 KB
scripts/tests/test_scan_scripts.pyscript4.1 KB
shapes/agent/assets/SKILL-template.mdmarkdown2.0 KB
shapes/agent/assets/capability-template.mdmarkdown582 B
shapes/agent/assets/customize-template.tomlconfig1.9 KB
shapes/agent/assets/sample-capability.mdmarkdown887 B
shapes/agent/shape.mdmarkdown3.2 KB
shapes/memory-agent/assets/BOND-template.mdmarkdown392 B
shapes/memory-agent/assets/CAPABILITIES-template.mdmarkdown1017 B
shapes/memory-agent/assets/CREED-template.mdmarkdown2.1 KB
shapes/memory-agent/assets/HOW-I-REMEMBER-template.mdmarkdown3.3 KB
shapes/memory-agent/assets/PERSONA-template.mdmarkdown705 B
shapes/memory-agent/assets/PULSE-template.mdmarkdown849 B
shapes/memory-agent/assets/SKILL-template-bootloader.mdmarkdown4.2 KB
shapes/memory-agent/assets/customize-template.tomlconfig1.2 KB
shapes/memory-agent/assets/first-breath-config-template.mdmarkdown4.5 KB
shapes/memory-agent/assets/first-breath-template.mdmarkdown9.3 KB
shapes/memory-agent/assets/init-sanctum-template.pyscript5.7 KB
shapes/memory-agent/assets/intake-capability-template.mdmarkdown975 B
shapes/memory-agent/assets/wake-template.pyscript6.8 KB
shapes/memory-agent/shape.mdmarkdown5.0 KB
shapes/multi-skill-module/assets/help-template.mdmarkdown623 B
shapes/multi-skill-module/assets/member-bmod-template.tomlconfig490 B
shapes/multi-skill-module/assets/record-SKILL-template.mdmarkdown374 B
shapes/multi-skill-module/assets/record-bmod-template.tomlconfig802 B
shapes/multi-skill-module/assets/retired-template.tomlconfig287 B
shapes/multi-skill-module/assets/roster-template.tomlconfig567 B
shapes/multi-skill-module/shape.mdmarkdown4.3 KB
shapes/plain-skill/assets/SKILL-template.mdmarkdown2.0 KB
shapes/plain-skill/assets/customize-template.tomlconfig1.0 KB
shapes/plain-skill/shape.mdmarkdown2.9 KB
shapes/rendered-agent/assets/SKILL-template.mdmarkdown1.0 KB
shapes/rendered-agent/assets/capability.mdmarkdown1.1 KB
shapes/rendered-agent/assets/customize-template.tomlconfig2.6 KB
shapes/rendered-agent/assets/workflow.mdmarkdown1.8 KB
shapes/rendered-agent/shape.mdmarkdown3.8 KB
shapes/rendered-skill/assets/SKILL-template.mdmarkdown1.0 KB
shapes/rendered-skill/assets/customize-template.tomlconfig990 B
shapes/rendered-skill/assets/step.mdmarkdown688 B
shapes/rendered-skill/assets/workflow.mdmarkdown1004 B
shapes/rendered-skill/shape.mdmarkdown2.2 KB
shapes/script-utility/assets/SKILL-template.mdmarkdown859 B
shapes/script-utility/assets/script-template.pyscript1.5 KB
shapes/script-utility/assets/test-template.pyscript1.2 KB
shapes/script-utility/shape.mdmarkdown1.6 KB
shapes/single-skill-module/assets/bmod-template.tomlconfig696 B
shapes/single-skill-module/assets/help-template.mdmarkdown177 B
shapes/single-skill-module/shape.mdmarkdown2.5 KB
ship.mdmarkdown6.4 KB

discover.md

View on GitHub
# Discover

The outcome is an execution plan the user approves before any file exists. A user with a hardened idea or who wants to move fast gets a confirmation and an execution plan, not an interview.

## Mine before you ask

Ask only for the gaps in what the user already gave, this conversation included.

## What you need to learn

Five things settle a skill:

- What it gets done and for whom. Two purposes are two skills.
- Who or what consumes the output, and what must be true of it for them to act without this conversation. This sets every bar.
- The phrases a user would type to reach it, and the nearby requests it must stay quiet on.
- What it runs on, and where the know-how lives that a model would not have, the corrections the user keeps making included.
- Whether the output can be checked objectively.

Ask where it will run: the user's own agent and model, an organisation whose harness and model are known, or distributed to people whose model is unknown.

Name only the one shape the answers reach:

- A persona with a menu is an agent.
- A persona whose capabilities teams must change without forking is a rendered agent.
- Memory across sessions is a memory agent.
- Teams swapping steps without forking is a rendered skill.
- Mostly deterministic work is a script-backed utility.
- Anything else is a plain skill.

Push back where the idea is thin:

- Is this a skill at all, or a one-off the user could ask for directly?
- A project convention belongs in the project's instructions file.
- A constraint a script could check belongs in a script.
- What input would break it?
- What should it require or recommend from the installed skills?

A skill whose job is to hold what the user would otherwise type every time (a format, a preference, a persona) is warranted by that alone. Do not test whether the model can follow it when told.

Where the skill instead claims to teach the model something, the target model is the user's own or their organisation's, and the user has not asked to move fast or run on their own, ask for one real input and run its trigger phrase alone, not the specification, through a subagent with no skill. If that gives what the user wants, say so and propose no skill, or one for only the part it got wrong. If it fails, the trace is the first evidence of what the skill has to teach.

For a distributed skill, offer a baseline eval on the user's cases at ship.

Offer what the outcome implies but nobody named: the sibling intent (update beside create), the unmentioned input. One line each; a decline is not re-proposed.

## Registration

Run `uv run {skill-root}/scripts/registry.py --project-root {project-root}`. Ask whether it is part of a module, naming any it could plausibly join, and whether the user plans more skills.

The guess is a single-skill module, except:

- Building or expanding an installed module, or a name carrying its prefix: member of that module.
- Planning more skills starts a module: settle its code now so nothing is renamed later. Built alone, the first skill takes the single-skill form; the record moves out when the second arrives.
- Several skills described: multi-skill module.
- No `_bmad/` and nothing said about BMad, or a user who wants no record: plain skill outside the registry.

A skill joining or starting a module takes the module's prefix.

## The Smithy execution plan

Present it under that title, and wait for a yes or changes:

- Name, kebab-case, proposed and asked. Suggest a prefix of the user's own, their org or module code, and say why in a line: it tells custom from core BMad, and a module's skills sort together. Do not propose `bmad-`; it belongs to modules shipped by the bmad-code-org, whose skills are `bmad-<code>-<skill>`, agents `bmad-<code>-agent-<name>`, the code dropped for core.
- One line on what it is for, who consumes the output, and what must be true of it for them to act.
- The description draft, as it will ship, written to the canon's description rule.
- Shape, with one line on why.
- Registration, with one line on why, naming the planned module and its code when this is its first skill. A `bmod-<code>/` record folder is never part of a one-skill execution plan. One of:
  - Single-skill module, the default: its own `bmod.toml` and `help/help.md` in the one folder, visible to `bmad` setup, help and updates.
  - Member of `bmod-<code>`: its `bmod.toml` names the record, whose skill list, help and, for an agent, roster change.
  - Plain skill outside the registry.
- Approach, with one line on why:
  - `lean` (default) when the user wants the skill.
  - `eval-first` when the output is checkable and the user wants proof.
  - `skill-creator-loop` when they want to iterate on measured results.
  - `scaffold` when they will write it themselves.
- Where it will live, proposed, not asked:
  - `{workflow.skills_folder}/<name>` when set.
  - Inside the module it joins.
  - Else `skills/<name>` at `{project-root}` when that folder holds `*/SKILL.md` (a skill repo, whose source is what to edit).
  - Else the folder the user's agent reads skills from (`.agents/skills/`, `.claude/skills/` or the like, writing at the symlink's target when one links to the other), live once written.
  - Else `~/.claude/skills/<name>` or `~/.agents/skills/<name>` when the skill is for the user everywhere or there is no project.
- The files it will have, one line each, and any script worth writing because the work is deterministic or would be rewritten every run.

Approval sets `{target}` and fixes the execution plan; later files work from it and do not re-ask. Then load `approaches/<approach>.md`.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall