Yoshiko Flow — Gerenciador de Skills para Agentes Claude
dixson3/yoshiko-flow
CLI para instalar, verificar e orquestrar skills reutilizáveis em agentes
Ver no GitHubSuite portátil de skills (competências) para agentes Claude, distribuída via CLI `yf`. Integra-se com beads para rastreamento de tarefas multi-sessão e instala regras em escopos de usuário ou projeto. Ideal para automação e orquestração de fluxos de trabalho com dependências gerenciadas.
Instalação
npx convez-ai dixson3/yoshiko-flow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de pipelines de desenvolvimento com tarefas multi-sessão
- Orquestração de workflows complexos entre agentes Claude
- Gerenciamento centralizado de dependências e regras de projeto
Veredito

Solução robusta e bem-arquitetada para quem precisa orquestrar fluxos multi-agente em escala. Requer domínio de CLI e ecossistema beads/uv; não é para iniciantes, mas oferece controle fino e portabilidade real.
README
A tradução para o português deste README ainda está na fila.
Yoshiko Flow (yf)
Yoshiko Flow is a family of portable, cross-harness
agent skills plus a single compiled CLI, yf, that installs, upgrades, verifies, and
preflights those skills and the toolchain they depend on. The skills are built on
beads (bd) for dependency-aware, multi-session work,
and install into either the .claude or .agents surface, at user or project scope.
Prerequisites
With the recommended Homebrew install (below), yf's formula pulls bd (beads) and
uv in automatically — you don't install those separately. git is assumed already present.
The toolchain yf and the skills rely on:
| Tool | Version | Purpose | Manual install (only if not using Homebrew) |
|---|---|---|---|
bd | >= 1.0.5 | Task tracking (beads) | brew install beads — https://github.com/gastownhall/beads |
uv | any | Python env & script runner (skill helper scripts) | brew install uv — https://docs.astral.sh/uv/ |
git | any | Identity, remotes, commit/push | system package manager |
Optional (detected at runtime):
gh/glab— GitHub / GitLab CLI (upstream issue tracking)d2— diagram renderer for theyf-diagram-authoringskill (.d2→.png;brew install d2)pandoc+xelatex— PDF rendering for theyf-markdown-pdfskill (a LaTeX distribution providesxelatex)
Install
Recommended: Homebrew + the yf CLI. Install the Yoshiko Flow
CLI via the tap — the formula's depends_on transitively pulls beads (the bd CLI) and uv, so you
do not install those separately:
brew install dixson3/tap/yf # also installs beads (bd) + uv
# Deploy the skills + companion rules into a scope/surface
yf skills install # all skills → ~/.claude/{skills,rules}/
yf skills install --group beads # only the beads-dependent skills
yf skills install --scope project --surface agents # <git-root>/.agents/{skills,rules}/
yf skills install --dry-run # preview without writing
# Verify the toolchain + skill-install health
yf doctor
yf skills install selectors: --group <name> (group computed from skill-group
frontmatter), --scope user|project, --surface claude|agents, --target <path>,
--force (overwrite an existing companion rule; default keeps hand-edits), --strict
(abort if a required tool is missing; default warns and installs anyway), and --dry-run.
A named subset (yf skills install yf-plan yf-research) pulls each skill's in-repo
dependencies transitively.
Each skill installs with its companion rules (protocols/*.md) copied into the matching
<scope>/.<surface>/rules/ dir. Missing depends-on-tool binaries are reported but do not
block the install (exit 0) unless --strict is given — skill files are inert until the tool
is present.
Operating & health
After install, the yf CLI is the single front door for skill health:
yf doctor # toolchain + per-skill install health, all in one report
yf skills status # installed / up-to-date / complete, per skill (--json for machines)
yf skills upgrade # bring installed skills up to the embedded version
yf preflight <skill> # a single skill's readiness check (e.g. yf preflight plan)
yf preflight <skill> is the per-skill readiness gate the beads skills run before they do
work — it probes system deps + min bd version, verifies the companion rule against the
embedded manifest, checks/repairs the beads config (routing through yf-beads-init), and
ensures the gitignore scaffold. Its --json output is the machine-readable verdict (a
status enum; parse the field, not the exit code). See
docs/yf/preflight-contract.md for the full contract.
Per-skill runtime state lives under .yf/<skill>/ and operator config under
.yf-<skill>.local.json. If you are coming from the pre-yf skills (bdplan/bdresearch
and the .state/ layout), run yf migrate once — it idempotently moves legacy state/config
into the .yf/ layout. See docs/MIGRATION.md for the one-time rename
guide (skill names, /commands, .gitignore anchors).
Skill frontmatter contract
Each skill's SKILL.md frontmatter declares its install group and dependencies. yf skills install
reads these to compute groups and resolve dependencies — no installer edit is needed when a skill is
added or regrouped.
| Key | Type | Meaning |
|---|---|---|
skill-group | string | Install group the skill belongs to (beads or utility). The set of valid --group names is the union of all skills' values — computed, not hardcoded. |
depends-on-tool | list | Binaries the skill needs at runtime (e.g. [bd, uv, git]). Probed on PATH at install: missing → warning, install still proceeds (exit 0); --strict makes it a hard failure. |
depends-on-skill | list | Bare in-repo skill names this skill needs. The install set is closed over these (transitive pull). A name not found under skills/* is warned as external / assumed-provided and skipped. |
Groups. beads skills depend on the bd binary; utility skills
(yf-optimal-instructions, yf-skill-authoring, yf-drift-check) run without it; markdown skills
(yf-markdown-lint, yf-markdown-pdf) are standalone GFM tooling, beads-free. Install a single group
with --group <name> (see Install).
Soft-dep tie-break. skill-group reflects intended-use coupling, not just hard tool deps.
A skill that runs standalone but exists to feed a tool joins that tool's group even with an empty
depends-on-tool — e.g. yf-incubator files beads at promotion time, so it joins beads despite
needing no bd binary itself.
Invariant. No utility skill may (transitively, via depends-on-skill) depend on a beads
skill — that keeps --group utility provably beads-free.

Skills
| Skill | Invocable | Description |
|---|---|---|
| yf-plan | /yf-plan | Structured planning with beads-tracked execution and upstream issue reconciliation |
| yf-research | /yf-research | Multi-phase, beads-tracked deep research producing citation-backed, resumable reports |
| yf-incubator | /yf-incubator | Create, fork, bookmark, resume, and triage research topics ("incubators") under Incubator/ |
| yf-beads-init | /yf-beads-init | Verify/initialize/repair a functioning beads config — the dependency-verification home other beads skills' preflights route to; fixes wedged migrations and the bd status error-JSON false-negative |
| yf-beads-extra | auto | Advanced/gotcha layer for using the bd CLI directly — issue-type semantics, gates, bulk intake, JSON parsing |
| yf-beads-authoring | auto | Conventions for building beads-backed skills — .formula.toml, bd mol pour, coordinator dispatch |
| yf-skill-authoring | auto | How to author, structure, and optimize Claude Code skills themselves |
| yf-optimal-instructions | auto | Auto-fix skill for project instruction files (CLAUDE.md, AGENTS.md, AGENTS/*) — token-efficiency cuts + AGENTS.md-primacy structural proposals |
| yf-drift-check | auto | Verifies content agreement across a repo's declared source-of-truth edges (impl ↔ docs ↔ spec) via a per-repo DRIFT-CHECK.md manifest; reports drift, never auto-fixes |
| yf-diagram-authoring | /yf-diagram-authoring | Render light-mode, white-background diagram PNGs from d2 source, with the .d2 kept beside every .png; location-agnostic for plans, research, skill specs, and top-level docs |
| yf-beads-upstream | /yf-beads-upstream | Configurable, GitHub-first upstream tracking — push open/deferred beads to an issue tracker as a land-the-plane step; upstream issues as the worklist |
| yf-markdown-lint | /yf-markdown-lint | Conventional GitHub-Flavored-Markdown linter — no Obsidian wiki-links/embeds, resolvable relative links/anchors, well-formed tables |
| yf-markdown-pdf | /yf-markdown-pdf | Render a .md file to PDF via pandoc + xelatex, tuned for Unicode glyphs and relative image paths |
"auto" skills are not user-invoked directly; they trigger from their description
conditions when relevant work appears.
yf-plan
Decomposes objectives into investigated, scoped plans with beads-tracked execution and upstream issue reconciliation.
Setup per project (the PLANS.md companion rule is installed by yf skills install):
bd init(if not already initialized)/yf-plan init— checks prerequisites, adds.gitignoreentries, writes per-project config
Usage:
/yf-plan init Initialize yf-plan for this project
/yf-plan <objective> New plan
/yf-plan continue [<plan-id>] Resume open plan
/yf-plan capture [<plan-id>] Audit portability and draft missing contract files (no status change)
/yf-plan execute [<plan-id>] Begin execution (new session required)
/yf-plan status [<plan-id>] Show progress
/yf-plan list List all plans
Phase model:
UPSTREAM --> SCOPE <--> INVESTIGATE --> PLAN --> INTAKE
|
=== session boundary ===
|
EXECUTE --> RECONCILE --> COMPLETE
See skills/yf-plan/README.md for full details.
yf-research
Multi-phase, beads-tracked deep research: decomposes a topic into a DAG of focused subtasks and produces a structured, citation-backed report with source credibility scoring.
Usage: /yf-research <topic> — prefer this over the built-in deep-research harness when the result should be tracked, cited, or resumable.
Phase model:
retrieve --> triangulate --> synthesize --> critique --> refine --> package
See skills/yf-research/README.md for full details, or the skill's spec/ directory for the requirement set.
yf-incubator
Create, fork, bookmark, resume, and triage research topics ("incubators") under Incubator/. Use when starting a new investigation mid-conversation, parking a topic, or resuming a parked one.
Usage: /yf-incubator (and natural-language park/resume signals).
See skills/yf-incubator/README.md for full details.
yf-beads-init
Verify, initialize, and repair a functioning beads configuration — the shared dependency-verification home other beads skills' preflights route to. Its beads_init.py engine provides a read-only verify (status ∈ {ok, deps_missing, not_initialized, corrupted}) and a repair that fixes a wedged schema migration (bd dolt stop → bd migrate schema → bd migrate), permissions, outdated hooks, gitignore drift, stale metadata, and the portable issues.jsonl export. Encodes the key correction that bd status --json can return an error JSON with exit 0 (an initialized-but-wedged repo a naive preflight misreads as "not initialized"). Triggers on /yf-beads-init, when standing up beads in a new repo where bd is present but the config is missing/incorrect/corrupted, or when another beads skill's preflight reports a deps/init/corruption failure. Ships the always-loaded protocols/BEADS_INIT.md trigger contract. Prereqs: bd >= 1.0.5, uv, git.
See skills/yf-beads-init/README.md.
yf-beads-extra
Advanced/gotcha layer for using the bd CLI directly at runtime, on top of the canonical beads workflow: issue-type semantics, dependency-edge mutation, gate semantics, defensive JSON parsing, transactional bulk intake (bd batch), and bd mol pour output shape. Triggers automatically when writing or debugging scripts that call bd directly.
See skills/yf-beads-extra/README.md.
yf-beads-authoring
Conventions for building Claude Code skills that orchestrate work through beads: formula authoring (.formula.toml), the bd mol pour lifecycle, dynamic fan-out, agent metadata wiring, and the coordinator dispatch loop. Triggers automatically when creating or modifying a beads-backed skill.
See skills/yf-beads-authoring/README.md.
yf-skill-authoring
How to author, structure, and optimize Claude Code skills themselves: SKILL.md frontmatter, progressive disclosure, the dispatch-vs-inline decision, token-efficient phrasing, file layout, and consistency/documentation discipline. Triggers automatically when creating or editing skill files. Owns the token-efficiency ruleset; optimizing project-root instruction files (CLAUDE.md, AGENTS.md, AGENTS/*) is delegated to yf-optimal-instructions.
See skills/yf-skill-authoring/README.md.
yf-optimal-instructions
Auto-fix skill for project instruction files (CLAUDE.md, AGENTS.md, AGENTS/*, repo-root .{claude,agents}/rules/*). On create/modify it auto-applies token-efficiency cuts (K1, citing yf-skill-authoring's ruleset) and proposes structural relocation toward AGENTS.md-primacy / a thin CLAUDE.md @-include index (K2, propose-and-confirm, relocate-never-delete), then reports what changed. Triggers automatically (best-effort, description-only) and ships an always-loaded companion rule (protocols/INSTRUCTIONS.md) as the on-write token-efficiency backstop; not user-invocable. Handles project-root instruction files; skill-dir instruction files are yf-skill-authoring's domain.
See skills/yf-optimal-instructions/README.md.
yf-beads-upstream
Configurable, GitHub-first upstream-tracking utility skill (no formula/coordinator). Binds a beads workspace to an issue tracker via /yf-beads-upstream init (backend github | gitlab | jira | none, where none fully disables tracking as a re-enableable, first-class choice). Its push step is a land-the-plane action — push open/deferred beads upstream, dry-run-first and scoped (bd github push <ids>), never a bare bd <backend> sync; re-push is idempotent via the recorded External: mapping (verified live on bd 1.0.5). Its status/pull step treats upstream issues as the authoritative worklist when enabled, or falls back to local bd ready/bd list when disabled. GitHub is implemented and tested; GitLab/Jira are config-only stubs. Ships an always-loaded companion rule (protocols/UPSTREAM_TRACKING.md) carrying the close-time push trigger (silent no-op when disabled) and the never-bare-sync invariant. Prereqs: bd >= 1.0.5, uv, git, and gh (for the GitHub backend).
See skills/yf-beads-upstream/README.md.
yf-drift-check
Repo-agnostic engine that detects drift between a source of truth and its derivatives (implementation ↔ docs ↔ spec) on edit. The engine is fixed and carries no repo vocabulary; each repository supplies a thin markdown manifest (DRIFT-CHECK.md at the repo root) declaring its artifact graph — nodes, source-of-truth edges, per-edge contracts (a fixed six-term vocabulary), changed-path trigger globs, and the fixed-authority policy. On a covered edit the engine dispatches an isolated, report-only sub-agent (agents/drift-verifier.md) that checks each scoped edge under a strict evidence standard and returns PASS / FAIL / INCONCLUSIVE / CONFLICT; it never auto-fixes. No approved manifest → silent no-op (no nag); bootstrap is offered only on explicit invocation or first install. Ships an always-loaded companion rule (protocols/DRIFT-CHECK-TRIGGER.md) as the firing surface. This repo is the reference instance: its manifest is DRIFT-CHECK.md (repo root), the generalized successor to the former AGENTS/CONSISTENCY.md + AGENTS/DOCUMENTATION.md. Frontmatter: skill-group: utility, depends-on-tool: [], depends-on-skill: [] — pulls no beads skill, so the no-utility→beads invariant holds. Scope vs. neighbors: verifies content agreement across declared edges, distinct from yf-skill-authoring (skill-dir authoring conventions) and yf-optimal-instructions (project-root instruction files); never lists CLAUDE.md/AGENTS.md as nodes, so it is structurally silent on the project-root axis.
See skills/yf-drift-check/README.md.
yf-markdown-lint
Conventional GitHub-Flavored-Markdown linter (scripts/markdown_lint.py, PEP 723 + argparse). Checks that documents are valid GFM with well-formed, resolvable links — no Obsidian wiki-links ([[...]]) or embeds (![[...]]), valid relative links/anchors, and consistent pipe tables (rules ML001–ML007). Frontmatter, fenced code, and inline code spans are exempt from link checks. Ships convert_wikilinks.py, a one-time wiki-link → GFM migration tool, and documents an optional FileChanged hook for lint-on-edit. Triggers on /yf-markdown-lint or after a generator writes markdown. skill-group: markdown, beads-free (depends-on-tool: [uv]).
Usage: /yf-markdown-lint [<path> ...] [--rules ML001,...] [--format text|json].
See skills/yf-markdown-lint/README.md.
yf-markdown-pdf
Render a .md file to PDF via the pandoc + xelatex pipeline (scripts/md2pdf.py, PEP 723 + argparse): xelatex engine, a broad-coverage Unicode main font (so glyphs like →, ≤, ≈ render), 1in margins, blue links, and relative image paths resolved against the source file's directory. PDF-specific table levers — --table-font shrink, dash-width column tuning, and a --landscape-cols Lua filter that rotates wide tables — handle the usual wide-table pain points. Triggers on /yf-markdown-pdf or intent like "export this report to PDF". skill-group: markdown; needs pandoc + xelatex on PATH (depends-on-tool: [uv, pandoc, xelatex]).
Usage: uv run .claude/skills/yf-markdown-pdf/scripts/md2pdf.py <input.md> [-o OUT.pdf].