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

scripts/prepass.py

View on GitHub
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = ["tiktoken"]
# ///
"""prepass: the deterministic pre-pass the review lenses read before opening any file.

One skill folder in, one JSON object out. Token counts come from count_tokens, path findings from
scan_paths and script findings from scan_scripts, all imported from this folder, so the numbers match
what each script prints on its own.

shape_hint is inferred, first match wins:
  memory-agent         `_bmad/memory` in SKILL.md, or scripts/wake.py or scripts/init-sanctum.py present
  rendered-agent       SKILL.md calls render_skill.py and customize.toml has an [agent] table
  rendered-skill       SKILL.md calls render_skill.py
  agent                customize.toml has an [agent] table
  single-skill-module  bmod.toml has both [bmod] and [skill]
  multi-skill-module   bmod.toml has [bmod] only (a module record)
  script-utility       scripts/ exists and SKILL.md is under 60 lines
  plain-skill          everything else; "unknown" when there is no SKILL.md

Usage:
  prepass.py <skill-folder>

Output, one JSON object on stdout:
  {"skill", "shape_hint", "files": [{"path", "tokens", "kind"}], "skill_md_tokens", "total_tokens",
   "has_customize", "has_scripts", "scripts": [{"path", "has_pep723", "has_test"}],
   "description_chars", "has_use_when", "frontmatter_ok", "bmod_kind", "path_findings": [...], "script_findings": [...],
   "long_paragraphs": [{"path", "line", "words", "longest_sentence"}]}
  kind is one of entry, prompt, script, test, asset, config, other.
  bmod_kind is none (no bmod.toml), skill (a module member), record (a record folder), record+skill (a
  single-skill module) or invalid (a file with neither table, or one that does not parse).
  long_paragraphs lists the lines of entry and prompt files past 150 words or holding a sentence past 60, a
  Markdown paragraph being one line; headings, tables, code fences and frontmatter are skipped.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
import tomllib
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))

from count_tokens import count_tokens, iter_text_files, read_text  # noqa: E402
from init_skill import USE_WHEN_RE, parse_frontmatter  # noqa: E402
from scan_paths import scan_skill  # noqa: E402
from scan_scripts import scan_scripts  # noqa: E402

MEMORY_RE = re.compile(r"_bmad/memory")
SCRIPT_UTILITY_MAX_LINES = 60
LONG_PARAGRAPH_WORDS = 150
LONG_SENTENCE_WORDS = 60
SENTENCE_END_RE = re.compile(r"(?<=[.?!])\s+")
FENCE_RE = re.compile(r"^(`{3,}|~{3,})")


def kind_of(rel: Path) -> str:
    parts = rel.parts
    if "assets" in parts[:-1]:
        return "asset"
    if parts[0] == "scripts":
        return "test" if "tests" in parts[1:-1] else "script"
    if rel.suffix == ".md":
        return "entry" if rel.name == "SKILL.md" and len(parts) == 1 else "prompt"
    if rel.suffix == ".toml":
        return "config"
    return "other"


def load_toml(path: Path) -> dict:
    try:
        return tomllib.loads(path.read_text(encoding="utf-8"))
    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError):
        return {}


def shape_hint(root: Path, skill_text: str | None) -> str:
    if skill_text is None:
        return "unknown"
    scripts = root / "scripts"
    if MEMORY_RE.search(skill_text) or (scripts / "wake.py").is_file() or (scripts / "init-sanctum.py").is_file():
        return "memory-agent"
    is_agent = "agent" in load_toml(root / "customize.toml")
    if "render_skill.py" in skill_text:
        return "rendered-agent" if is_agent else "rendered-skill"
    if is_agent:
        return "agent"
    bmod = load_toml(root / "bmod.toml")
    if "bmod" in bmod:
        return "single-skill-module" if "skill" in bmod else "multi-skill-module"
    if scripts.is_dir() and len(skill_text.splitlines()) < SCRIPT_UTILITY_MAX_LINES:
        return "script-utility"
    return "plain-skill"


def bmod_kind(root: Path) -> str:
    manifest = root / "bmod.toml"
    if not manifest.is_file():
        return "none"
    data = load_toml(manifest)
    has_record = isinstance(data.get("bmod"), dict)
    has_skill = isinstance(data.get("skill"), dict)
    if has_record and has_skill:
        return "record+skill"
    if has_record:
        return "record"
    if has_skill:
        return "skill"
    return "invalid"


def long_paragraphs(text: str) -> list[dict]:
    lines = text.splitlines()
    start = 0
    if lines and lines[0].strip() == "---":
        start = next((i for i, line in enumerate(lines[1:], 2) if line.strip() == "---"), 0)
    found = []
    fence = ""
    for number, line in enumerate(lines[start:], start + 1):
        stripped = line.strip()
        marker = FENCE_RE.match(stripped)
        if fence:
            if marker and stripped == marker[1] and stripped[0] == fence[0] and len(stripped) >= len(fence):
                fence = ""
            continue
        if marker:
            fence = marker[1]
            continue
        if stripped.startswith(("#", "|")):
            continue
        words = len(stripped.split())
        longest = max(len(s.split()) for s in SENTENCE_END_RE.split(stripped))
        if words > LONG_PARAGRAPH_WORDS or longest > LONG_SENTENCE_WORDS:
            found.append({"line": number, "words": words, "longest_sentence": longest})
    return found


def build(root: Path) -> dict:
    skill_path = root / "SKILL.md"
    skill_text = read_text(skill_path) if skill_path.is_file() else None

    files = []
    long_lines = []
    skill_md_tokens = 0
    for path in iter_text_files(root):
        rel = path.relative_to(root)
        text = read_text(path)
        tokens, _ = count_tokens(text)
        kind = kind_of(rel)
        files.append({"path": rel.as_posix(), "tokens": tokens, "kind": kind})
        if kind in ("entry", "prompt"):
            long_lines.extend({"path": rel.as_posix(), **found} for found in long_paragraphs(text))
        if path == skill_path:
            skill_md_tokens = tokens

    meta = parse_frontmatter(skill_text)[0] if skill_text is not None else None
    description = (meta or {}).get("description", "")
    frontmatter_ok = bool(
        meta and meta.get("name") == root.name and description and set(meta) <= {"name", "description"}
    )

    scripts_result = scan_scripts(root)
    return {
        "skill": root.name,
        "shape_hint": shape_hint(root, skill_text),
        "files": files,
        "skill_md_tokens": skill_md_tokens,
        "total_tokens": sum(f["tokens"] for f in files),
        "has_customize": (root / "customize.toml").is_file(),
        "has_scripts": (root / "scripts").is_dir(),
        "scripts": [
            {"path": s["path"], "has_pep723": s["has_pep723"], "has_test": s["has_test"]}
            for s in scripts_result["scripts"]
        ],
        "description_chars": len(description),
        "has_use_when": bool(USE_WHEN_RE.search(description)),
        "frontmatter_ok": frontmatter_ok,
        "bmod_kind": bmod_kind(root),
        "path_findings": scan_skill(root)["findings"],
        "script_findings": scripts_result["findings"],
        "long_paragraphs": long_lines,
    }


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("skill", type=Path, help="skill folder to analyze")
    args = p.parse_args(argv)
    root = args.skill.expanduser().resolve()
    if not root.is_dir():
        p.error(f"not a directory: {args.skill}")
    print(json.dumps(build(root), indent=2))
    return 0


if __name__ == "__main__":
    sys.exit(main())
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: 471kUpdated 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