jlevy/flowmark / src/flowmark/skills
flowmark
VerifiedFast, consistent Markdown auto-formatter for typographic cleanup, normalization, and clean semantic line breaks. Use when creating, editing, or cleaning Markdown; formatting LLM-generated docs; adopting Flowmark in a repository; adding Markdown format scripts or commit hooks; or replacing Prettier or another Markdown formatter.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.4 KB |
| __init__.py | script | 0 B |
| references/project-setup.md | markdown | 3.7 KB |
references/project-setup.md
View on GitHub# Project Setup and Migration
Use this workflow when adopting Flowmark across a repository.
Keep one `flowmark` skill; project setup is a use case of that skill, not a separate
skill.
## Migration Checklist
1. Find the Markdown sources and identify generated, vendored, fixture, and golden files
that must retain byte-exact content.
2. Add those paths to `.flowmarkignore`.
3. Make Flowmark the only formatter that owns Markdown.
Disable Markdown in Prettier, Biome, dprint, editor format-on-save settings, and
existing Markdown hooks.
4. Add one pinned project command and run it once over the repository.
Review and commit the baseline reformat separately from content changes.
5. Add an auto-fixing commit hook.
Prefer a hook that stages its fixes so formatting does not become a manual gate.
6. Do not fail the main build only for ordinary Markdown formatting drift.
Keep formatting local and automatic; reserve CI drift checks for generated or
contractually byte-exact documentation.
## Pinned Project Command
Prefer the Rust port through `uvx`:
```makefile
FLOWMARK := uvx --from flowmark-rs==__FLOWMARK_RS_VERSION__ flowmark
.PHONY: format-docs
format-docs:
$(FLOWMARK) --auto .
```
Passing `.` lets Flowmark discover files once and honor `.gitignore` and
`.flowmarkignore` from the repository root.
Avoid shell `find` pipelines or per-directory invocations unless the repository requires
them.
Start `.flowmarkignore` with content Flowmark must not rewrite:
```gitignore
# Generated or vendored Markdown
docs/api/_generated/
third_party/
# Byte-exact fixtures and golden files
tests/fixtures/
tests/golden/
```
When documentation is generated, format canonical sources first, then regenerate their
mirrors. Exclude generated mirrors from Flowmark so there is one source of truth.
## Auto-Fix on Commit
Lefthook can format and stage Markdown without turning style into a separate failure:
```yaml
pre-commit:
commands:
flowmark:
glob: "*.{md,mdc,markdown}"
run: uvx --from flowmark-rs==__FLOWMARK_RS_VERSION__ flowmark --auto --force-exclude {staged_files}
stage_fixed: true
```
`--force-exclude` applies `.flowmarkignore` even though the hook passes explicit file
paths. If generated docs must be refreshed after formatting, call one repository script
or Make target that performs both operations in the required order.
For the `pre-commit` framework, use a local system hook with the same pinned command:
```yaml
repos:
- repo: local
hooks:
- id: flowmark
name: flowmark
entry: uvx --from flowmark-rs==__FLOWMARK_RS_VERSION__ flowmark --auto --force-exclude
language: system
files: '\.(md|mdc|markdown)$'
```
Keep both hook selectors aligned with any Markdown extensions the repository discovers
through `--extend-include`. The `pre-commit` framework stops the first commit after
modifying files; stage the fixes and retry.
Use Lefthook with `stage_fixed: true` when transparent auto-staging is preferred.
## Disable Competing Markdown Formatters
For Prettier, exclude Markdown in `.prettierignore`:
```gitignore
*.md
```
Also remove Markdown-specific Prettier hooks and editor defaults.
If Flowmark owns MDX or another extension via `--extend-include`, exclude that extension
from Prettier too.
Apply the same ownership rule to other tools: keep them for code and data formats, but
remove Markdown from their include globs and format-on-save configuration.
Do not run two Markdown formatters sequentially; they can churn each other’s output and
make hooks or CI nondeterministic.
<!-- This document follows common-doc-guidelines.md.
See github.com/jlevy/practical-prose and review guidelines before editing.
-->
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |