fskill-creator: turning a bloated SKILL.md into a tested function pipeline
fskill-creator turns your long-text SKILL into functions, making it modular, testable and trackable for better long-term maintenance and iteration
At a glance
- What is it?
- fskill-creator is a skills.sh skill that rewrites long agent skills as explicit input/output functions with trace logs and unit tests. It is a maintenance methodology, not a runtime, and it only pays off once a skill has already grown past hand editing.
- Who is it for?
- Adopt fskill-creator if you maintain a skill whose SKILL.md and references/ have grown past manual review and you want regression checks instead of gut feeling. Do not adopt it for a short, already modular skill: the README says so directly, and the extra scripts, testcases and logs are overhead you would never exercise.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 81 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem fskill-creator is aimed at: a SKILL.md that only grows
Agent skills rot in a specific way. A step gains a patch, an edge case gets another rule, a workaround is appended to references/, and after a dozen iterations the skill is a wall of prose where nobody can say which sentence caused a regression. The README calls this out as the target condition and shows a diagram of the mess: SKILL.md, a workflow with a "Step 1.5 patch", rules and stop rules, an output handler, references/rules.md, references/examples.md, and four scripts whose names include parse_input_new.js, fix_edge_case_once.sh and migrate_old_do_not_delete.js. That last filename is the honest part of the pitch.
The intended audience is narrow. The README states the methodology is "designed for complex Skill maintenance and iteration", and then inverts the sales pitch: if your skill is concise, or you have already split it cleanly and are confident it is maintainable, you do not need to make it functional. That is an unusually direct disqualification of most small skills, and it is the right one. A three-step skill with no scripts gains nothing from a test suite.
How the functional layout works: functions, references, scripts, testcases
The model has two layers. In the execution layer, SKILL.md does orchestration only. Each step becomes a function with explicit input and output, described as pure-function-first, and the README's diagram shows a composition of four: load_input, extract, generate, validate, chained so each one's output is the next one's input. The supporting layer is read-only from the pipeline's point of view: references/, scripts/, testcases/ and logs/runs/.
The division of labour is stated as a rule rather than a suggestion. Judgment goes into functions. Rules shared across functions go into references/. Deterministic work that a function calls, such as parsing, formatting and validation, goes into scripts/. Real failures and ideal runs get captured as testcases. The README's framing is that complexity should sit where it belongs rather than be removed; a skill does not get simpler, it gets sorted.
Trace logging is part of the generated output, not something you add later. scripts/runtime.mjs exports runStep, writeStepReport and applyReportMode for wrapping each step, and scripts/report.mjs writes function-level logs with report_mode=off|local|remote. When report_mode is local, JSONL traces land in logs/runs/. Each record covers input, output, token consumption and duration, per the README's description of the logging capability.
Installing fskill-creator and running the create lane
Installation goes through skills.sh. The README gives one command, and notes that adding -a <agent> targets a single agent while -g should only be used if that agent supports global install.
npx skills add AGI-comming/functional-skill-creator --skill fskill-creator -yAfter that, the skill is invoked as a slash command with a workflow brief. The README's example is deliberately abstract, because the argument is your own workflow description:
/fskill-creator create a functional skill for <workflow>What you should end up with is a skill directory laid out the functional way: an orchestrating SKILL.md, references/ for shared rules, scripts/ for deterministic logic, testcases/ for assertions, and the report and test tooling. The README lists three optional switches that are on by default: include_report, include_unittest and include_viewers. Setting any of them to false skips that piece, which is how you get a leaner skill when you do not want local viewers or a report runtime.
Migrating an existing skill directory instead of starting over
The migrate lane is the one most readers will actually need, since the pain arrives after a skill exists. It takes a path to a skill directory:
/fskill-creator migrate <path-to-skill-dir>The README is explicit that this reads the whole package, meaning SKILL.md, references/, scripts/ and other companion files, rather than a single markdown file in isolation. That distinction matters: a migration that only saw SKILL.md would miss the rules and helper scripts that the new function boundaries have to account for.
The repository itself is the reference implementation of the output. The check script runs the skill's own test cases and lint passes over skills/fskill-creator and its sub-skills, and over examples/meeting-notes-to-actions, which is the worked example shipped with the repo. Reading that example directory alongside its normalize_meeting_notes.test.mjs is the cheapest way to see what a finished functional skill looks like before you point the migrate lane at your own.
Where this approach costs you: boundaries, rollback and the wrong-sized skill
The hard part of functional decomposition is deciding where one function ends and the next begins, and that decision is judgment, which the methodology pushes into the functions themselves. The tooling can propose a pipeline; it cannot tell you whether validate belongs inside generate or after it. Get the boundaries wrong and you have replaced one tangled skill with several smaller skills that are individually testable and collectively confusing.
Rollback is the gap. The README documents the migrate lane's inputs and what it reads, and it documents the report and test tooling, but it does not document what happens to the original skill directory during a migration or how to undo one. Treat that as unknown until you check it: run migrate against a copy, not your working skill.
There is also a real mismatch case. A skill whose steps are mostly judgment calls with no deterministic core gets scripts/ and testcases/ directories that stay nearly empty, while the function wrappers add indirection to something a reader could previously follow in one pass. The README's own test suite reflects the tool's weight: the check script chains five commands covering skill scripts, example scripts, test cases and two lint passes. That is reasonable for a maintained skill and excessive for a prompt you edit twice a year.
How fskill-creator differs from a plain skill creator
A conventional skill creator scaffolds a skill: it produces SKILL.md, a references directory, maybe a starter script, and leaves maintenance to you. The output is a well-formed package. fskill-creator's output is a well-formed package plus a runtime contract: every step is a function with declared input and output, every function can be wrapped with runStep, traces accumulate as JSONL in logs/runs/, and scripts/test_cases.mjs runs assertions over testcases/**/*.case.json.
The practical difference shows up in the iteration loop. With a plain scaffold, a regression is investigated by reading the skill and reasoning about what changed. Here, the README describes turning real execution traces into regression assets: test_cases.mjs can export trace records as testcases, so a failure you captured in logs/runs/ becomes a repeatable assertion. That is a different lifecycle, and it is why the README insists the methodology is for skills under continuous iteration rather than for skills being written once.
Editorial conclusion
Adopt fskill-creator if you maintain a skill whose SKILL.md and references/ have grown past manual review and you want regression checks instead of gut feeling. Do not adopt it for a short, already modular skill: the README says so directly, and the extra scripts, testcases and logs are overhead you would never exercise. Before committing, run the migrate lane on a copy of one real skill directory and read the proposed function boundaries; that proposal is the part you will have to live with, and the README does not document rollback for a migration that gets them wrong.
Frequently asked questions
Can you give me an example of a functional skill?
The repository ships one at examples/meeting-notes-to-actions, complete with a normalize_meeting_notes.test.mjs file. The README also sketches the shape generically as a composition of load_input, extract, generate and validate, each with explicit input and output.
What does skill Creator do?
In this project, fskill-creator turns a long-text skill into functions so the skill becomes modular, traceable and testable. It has two lanes: create a new functional skill from a workflow brief, or migrate an existing skill directory by reading its SKILL.md, references/, scripts/ and companion files.
What are some examples of functional technical skills?
The README does not list example technical skills. It gives one worked example in the repository, examples/meeting-notes-to-actions, and describes the general pattern as steps decomposed into functions with explicit Input/Output.
What do you mean by functional skills?
Here it means treating each Step as a Function with explicit Input/Output, pure function first, where SKILL.md only orchestrates the pipeline and consumes external inputs and reference dependencies. Shared rules move to references/, deterministic logic moves to scripts/.
Community notes