pflow-skills

A curated catalog of Agent Skills for everyday development workflows — installable into Claude Code, Cursor, OpenCode, and any skills.sh-compatible agent.

Skills are small, composable folders of instructions and scripts that teach your agent to do one task well. No application code here — just the skills.

Quickstart

Install the whole catalog into the current project (30 seconds):

npx skills add phpinfo/pflow-skills

Or pick a single skill:

npx skills add phpinfo/pflow-skills -s pflow-commit

Flag	Effect
(default)	Install into the project (.agents/skills/)
-g, --global	Install for every project (~/.agents/skills/)
--copy	Copy files instead of symlinking

Skills

Skill	What it does
pflow-commit	Analyzes your working tree, writes a Conventional Commit message, then commits and pushes. Invoked manually.
pflow-task-add	Adds a new task to the mdtodo task list. The agent clarifies the task’s essence, formulates a concise title and description with expected result, then adds it via mdtodo. Invoked manually.
pflow-task-plan	Builds a concrete implementation plan for the current active mdtodo task. The agent clarifies open questions, analyzes the codebase and docs, decomposes the work into small steps, and saves the plan to a file. Plans only — does not implement. Invoked manually.
pflow-task-implement	Implements the saved plan for the current active mdtodo task. The agent reads the plan from PFLOW_TASKS_PLAN_FILE, reviews it critically, decomposes it into todos, then executes each step in order with verification. Implements only — does not plan, commit, or close the task. Invoked manually.
pflow-task-next	Takes the next mdtodo task into progress and creates a git branch named for it (feature/, fix/, chore/). Requires a clean working tree on the dev branch. Invoked manually.
pflow-task-finish	Closes the current mdtodo task; when pflow-commit is installed, branches the work, commits it, and merges into dev. Degrades to mdtodo-only with a warning otherwise. Invoked manually.
pflow-changelog	Generates a Keep a Changelog entry for the current feature version based on completed tasks and git commits, prepends it to CHANGELOG.md, then commits and pushes. Requires a clean working tree on the dev branch. Invoked manually.
pflow-refactor	Performs evidence-based refactoring research for a code, component, or subsystem. Produces an As Is analysis and a minimal, justified To Be proposal with naming, dependency, migration, and trade-off recommendations. Applies SOLID, KISS, YAGNI, DRY, Law of Demeter, and composition over inheritance. Analysis only — does not implement changes. Invoked manually.

Configuration

Most skills work with zero configuration. pflow-task-finish accepts optional settings, supplied as CLI arguments (passed by the agent to its script) or as environment variables — either exported in your shell or placed in a .env file at the project root, which the script loads automatically (parsed, never executed; values already set in the real environment take precedence).

pflow-commit

Requires: none.

pflow-task-finish

Requires: pflow-commit (optional — without it, the task is closed via mdtodo but all git steps are skipped with a warning).

CLI arguments (task-finish.sh):

Argument	Required	Description
--message "<msg>"	yes (when committing)	Conventional Commit message for the finished work. Ignored in fallback mode (no pflow-commit), where no commit happens.
--slug "<slug>"	no	Kebab-case name for the task branch (task/<slug>). Defaults to a slug derived from the current task title. Ignored when finishing from a non-dev branch (see below).
--dev "<branch>"	no	Branch to merge the task branch into. Highest-priority override of the dev branch (see below).

Environment variables (env or .env):

Variable	Default	Description
PFLOW_TASKS_MDTODO_FILE	(mdtodo’s own default, todo.md)	Path to the Markdown todo list. Exported as MDTODO_FILE once before any mdtodo call, so the whole flow operates on this file.
PFLOW_GIT_DEV_BRANCH	dev	Branch the task branch is merged into. If the chosen branch does not exist, the work merges into the branch you started on.
MDTODO_FILE	todo.md	Read directly by the mdtodo CLI. PFLOW_TASKS_MDTODO_FILE sets this for you; set it yourself if you prefer.

Dev-branch precedence: --dev flag → PFLOW_GIT_DEV_BRANCH → autodetected dev/develop → default dev. If the resolved branch is absent, the merge target falls back to the branch you started on.

Branch reuse: when run from a non-dev branch (e.g. one created by pflow-task-next), it commits and merges THAT branch instead of creating task/<slug>. Creating task/<slug> only happens when finishing straight from the dev branch.

pflow-task-add

Requires: none.

CLI arguments (task-add-run.sh):

Argument	Required	Description
--title "<title>"	yes	Concise task name (single line).
--description "<desc>"	no	Expected result and key details. Inserted as indented lines under the task in the markdown file.
--version "<version>"	no	Version tag in vX.Y.Z format, only when the user specifies one.

Environment variables (env or .env):

Variable	Default	Description
PFLOW_TASKS_MDTODO_FILE	(mdtodo’s own default, todo.md)	Path to the Markdown todo list. Exported as MDTODO_FILE before any mdtodo call.

pflow-task-plan

Requires: mdtodo CLI.

Scripts: plan-context.sh (resolves the tasks file and reads the active task), plan-save.sh (reads the plan Markdown from stdin and writes it to PFLOW_TASKS_PLAN_FILE).

Environment variables (env or .env):

Variable	Default	Description
PFLOW_TASKS_MDTODO_FILE	(mdtodo’s own default, todo.md)	Path to the Markdown todo list. Used to read the current active task.
PFLOW_TASKS_PLAN_FILE	./tmp/pflow-tasks-plan.md	Path the generated plan is written to. Parent directories are created automatically.

pflow-task-implement

Requires: mdtodo CLI; a plan file produced by pflow-task-plan.

Scripts: implement-context.sh (resolves the tasks file, reads the active task, and verifies the plan file exists and is non-empty).

Environment variables (env or .env):

Variable	Default	Description
PFLOW_TASKS_MDTODO_FILE	(mdtodo’s own default, todo.md)	Path to the Markdown todo list. Used to read the current active task.
PFLOW_TASKS_PLAN_FILE	./tmp/pflow-tasks-plan.md	Path the plan is read from. Must match the value used by pflow-task-plan.

pflow-task-next

Requires: none.

CLI arguments (task-next-branch.sh):

Argument	Required	Description
--branch "<type/slug>"	yes	Name of the branch to create and switch to (e.g. feature/login-form). Composed by the agent from the task.

Environment variables (env or .env):

Variable	Default	Description
PFLOW_TASKS_MDTODO_FILE	(mdtodo’s own default, todo.md)	Path to the Markdown todo list. Exported as MDTODO_FILE before any mdtodo call.
PFLOW_GIT_DEV_BRANCH	dev	Branch the new task branch must be created from. The skill errors unless you are on this branch with a clean working tree.

pflow-changelog

Requires: pflow-commit (reuses git-lib.sh for commit/push).

Environment variables (env or .env):

Variable	Default	Description
PFLOW_FEATURES_MDTODO_FILE	(required)	Path to the Markdown features list. Used to determine the current feature and its version.
PFLOW_TASKS_MDTODO_FILE	(mdtodo’s own default, todo.md)	Path to the Markdown tasks list. Used to list completed tasks.
PFLOW_GIT_DEV_BRANCH	dev	Branch the skill must run on. Errors if current branch differs.

How it works

Each skill is a self-contained folder under skills/:

skills/
└── <name>/
    ├── SKILL.md        # frontmatter (name, description, allowed-tools) + instructions
    └── scripts/        # executable helpers the skill calls

The agent reads every SKILL.md description up front and triggers the matching skill when the task fits. Heavy logic lives in scripts/ so the prompt stays short and reliable.

Creating a skill

1. Add skills/<name>/SKILL.md with YAML frontmatter (name, description, and allowed-tools for any scripts).
2. Make scripts executable and reference them by their installed path — .agents/skills/<name>/scripts/....
3. Add a row to the Skills table above.

Write the description to say plainly what the skill does and when it fires — it’s the signal the agent uses to decide whether to reach for it.

License

MIT