Skip to content

jlevy/flowmark / src/flowmark/skills

flowmark

Verified

Fast, 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.

FileKindSize
SKILL.mdskill md2.4 KB
__init__.pyscript0 B
references/project-setup.mdmarkdown3.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.
-->
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: 470kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexUnverifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall