Skip to content
Back to search

functional-skill-creator

fskill-creator turns your long-text SKILL into functions, making it modular, testable and trackable for better long-term maintenance and iteration

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agi-comming--functional-skill-creator/badge.svg)](/listings/agi-comming--functional-skill-creator)

HTML

<a href="/listings/agi-comming--functional-skill-creator"><img src="/api/listings/agi-comming--functional-skill-creator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

npx skills add AGI-comming/functional-skill-creator --skill fskill-creator -y

Install via [skills.sh](https://skills.sh/). Add `-a <agent>` to target one agent; add `-g` only if it supports global install.

---

Usage

**Create** — new functional skill from a workflow brief:

/fskill-creator create a functional skill for <workflow>

**Migrate** — convert an existing legacy skill directory into a functional skill:

/fskill-creator migrate <path-to-skill-dir>

The migrate lane reads the whole skill package — `SKILL.md`, `references/`, `scripts/`, and other companion files — not a single markdown file in isolation.

Optional: `include_report`, `include_unittest`, `include_viewers` (on by default; set to `false` to skip).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 231 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Functional Skill Creator
  2. > **Maintain Agent Skills with functional programming discipline.**
  3. [中文版 README](docs/README.zh-CN.md)
  4. Functional Skill is an engineering methodology, **designed for complex Skill maintenance and iteration.**
  5. Combined with trace logging and unit testing, it makes Skills **modular, traceable, and testable**:
  6. - Treat each `Step` as a `Function` with explicit `Input/Output` (pure function first)
  7. - `SKILL.md` only orchestrates the pipeline of `Function`s, consuming only `external inputs` and `reference dependencies`
  8. - Shared rules across `Function`s go into `references/`
  9. - Deterministic logic called by `Function`s becomes `scripts/`
  10. - Add trace logging for every `Function`, running locally, recording input/output/token consumption/duration
  11. - Equip every `Function` with unit tests and E2E tests, ensuring neither individual Functions nor the full pipeline regress
  12. ## Quick Start
  13. ### Install
  14. ```bash
  15. npx skills add AGI-comming/functional-skill-creator --skill fskill-creator -y
  16. ```
  17. Install via [skills.sh](https://skills.sh/). Add `-a <agent>` to target one agent; add `-g` only if it supports global install.
  18. ---
  19. ### Usage
  20. **Create** — new functional skill from a workflow brief:
  21. ```text
  22. /fskill-creator create a functional skill for <workflow>
  23. ```
  24. **Migrate** — convert an existing legacy skill directory into a functional skill:
  25. ```text
  26. /fskill-creator migrate <path-to-skill-dir>
  27. ```
  28. The migrate lane reads the whole skill package — `SKILL.md`, `references/`, `scripts/`, and other companion files — not a single markdown file in isolation.
  29. Optional: `include_report`, `include_unittest`, `include_viewers` (on by default; set to `false` to skip).
  30. ## Why
  31. Your Skill is getting bloated.
  32. As your Skill's capabilities iterate, your `SKILL.md` and `references/*.md` grow longer, rules pile up, edge cases get patched ever more finely — slowly turning into an unmaintainable wall of prose.
  33. A typical example is when everything keeps getting stuffed into a handful of markdown files:
  34. ### Before: monolithic prose wall
  35. ```mermaid
  36. flowchart TB
  37. subgraph mono["Monolithic Skill — tangled dependencies"]
  38. SKILL["SKILL.md<br/>Goal · Workflow · Rules · Output · Known issues"]
  39. W["Workflow + Step 1.5 patch"]
  40. RL["Rules · edge cases · stop rules"]
  41. OUT["Output handler · validation"]
  42. RULES["references/rules.md<br/>Terms · policies · snippets"]
  43. EX["references/examples.md<br/>Success · failures · workarounds"]
  44. S1["parse_input.js"]
  45. S2["parse_input_new.js"]
  46. S3["fix_edge_case_once.sh"]
  47. S4["migrate_old_do_not_delete.js"]
  48. end
  49. SKILL <--> W
  50. SKILL <--> RL
  51. W <--> RL
  52. RL <--> OUT
  53. SKILL <--> RULES
  54. RULES <--> EX
  55. EX <--> W
  56. OUT <--> EX
  57. W --> S1
  58. RL --> S2
  59. S1 <--> S2
  60. S2 --> S3
  61. S3 <--> EX
  62. OUT --> S4
  63. S4 <--> SKILL
  64. S3 <--> RL
  65. S1 --> OUT
  66. style mono fill:#fff5f5,stroke:#c53030
  67. style SKILL fill:#fde8e8,stroke:#c53030
  68. style W fill:#fde8e8,stroke:#c53030
  69. style RL fill:#fde8e8,stroke:#c53030
  70. style OUT fill:#fde8e8,stroke:#c53030
  71. style RULES fill:#fde8e8,stroke:#c53030
  72. style EX fill:#fde8e8,stroke:#c53030
  73. style S1 fill:#fde8e8,stroke:#c53030
  74. style S2 fill:#fde8e8,stroke:#c53030
  75. style S3 fill:#fde8e8,stroke:#c53030
  76. style S4 fill:#fde8e8,stroke:#c53030
  77. ```
  78. Functional Skill Creator provides an engineering methodology that makes Skills **modular, traceable, and testable**:
  79. - Break each step into a `Function` with explicit Input/Output
  80. - `SKILL.md` only orchestrates the pipeline of `Function`s, consuming only `external inputs` and `reference dependencies`
  81. - Shared rules across `Function`s go into `references/`
  82. - Deterministic logic called by `Function`s becomes `scripts/`
  83. - Add trace logging for every `Function`, running locally, recording input/output/token consumption/duration
  84. - Equip every `Function` with unit tests and E2E tests, ensuring neither individual Functions nor the full pipeline regress
  85. ### After: observable functional pipeline
  86. ```mermaid
  87. flowchart TB
  88. subgraph exec["execution — compose(f₄ ∘ f₃ ∘ f₂ ∘ f₁)"]
  89. direction LR
  90. ORCH["SKILL.md<br/>orchestration only"] --> F1["f₁ load_input<br/>(raw) → loaded"] --> F2["f₂ extract<br/>(loaded) → req"] --> F3["f₃ generate<br/>(req) → plan"] --> F4["f₄ validate<br/>(plan) → out"]
  91. end
  92. subgraph sup["supporting layers — read-only dependencies"]
  93. direction LR
  94. REF["references/"] --- SCR["scripts/"] --- TC["testcases/"] --- LOG["logs/runs/"]
  95. end
  96. exec --- sup
  97. style exec fill:#f0fff4,stroke:#2f855a,stroke-width:2px
  98. style sup fill:#ebf8ff,stroke:#2b6cb0,stroke-width:2px
  99. style ORCH fill:#e6ffed,stroke:#2f855a
  100. style F1 fill:#e6ffed,stroke:#2f855a
  101. style F2 fill:#e6ffed,stroke:#2f855a
  102. style F3 fill:#e6ffed,stroke:#2f855a
  103. style F4 fill:#e6ffed,stroke:#2f855a
  104. style REF fill:#ebf8ff,stroke:#2b6cb0
  105. style SCR fill:#ebf8ff,stroke:#2b6cb0
  106. style TC fill:#ebf8ff,stroke:#2b6cb0
  107. style LOG fill:#ebf8ff,stroke:#2b6cb0
  108. ```
  109. Functional Skill does not aim to make Skills complex, but to put complexity where it belongs: judgment goes to Functions, rules go into references, deterministic actions go to scripts, and regression behavior solidifies into testcases.
  110. ## When to Use
  111. - You are maintaining a long-evolving agent skill and don't want to rely on gut feeling for every regression check.
  112. - Your `SKILL.md` and `references/` have become impossible to maintain manually, leaving you no choice but to blindly let AI iterate down one path.
  113. - You want to extract deterministic work like parsing, formatting, and validation from prompts and execute them reliably through scripts.
  114. - You want your skill's functionality and execution flow to become traceable, so you can pinpoint exactly where each run went wrong.
  115. - You want your skill to capture real failure cases and ideal runs, turning them into repeatable test suites.
  116. In other words, if your Skill is concise, or you've already split it cleanly in a modular way and are confident it's maintainable — you don't need to make it Functional.
  117. ## Report Log and Unittest Capabilities
  118. Skills generated by `fskill-creator` include basic report / unittest tooling by default. Use `include_report=false` and `include_unittest=false` to disable them separately, or use `include_viewers=true|false` to control whether local viewers are generated.
  119. - `scripts/report.mjs`: Writes function-level report logs, supports `report_mode=off|local|remote`.
  120. - `scripts/runtime.mjs`: Exports `runStep`, `writeStepReport`, and `applyReportMode` for wrapping each Step in the function workflow.
  121. - `scripts/test_report.mjs`: Validates that the report runtime can write JSONL and checks sensitive field redaction.
  122. - `scripts/test_cases.mjs`: Runs `testcases/**/*.case.json` function input/output assertions, and can also export trace records as testcases.
  123. - `logs/runs/`: JSONL traces written when `report_mode=local`.
  124. ## Iteration Loop
  125. Functional Skill encourages turning real execution traces into regression assets:
  126. ```text
  127. Run skill → Check trace → Review function behavior → Export testcase → Fix function → Run tests
  128. ```
  129. If `Function1` fails, add a testcase for `Function1`;
  130. if `normalize_input` is deterministic logic, push it down into `scripts/` and write a script test.
  131. Problems stay at the layer where they occur — maintenance cost does not spread across the entire skill.
  132. See methodology details in [docs/functional-skill.md](docs/functional-skill.md). Function contract specification in [docs/function-contract.md](docs/function-contract.md). When to put logic into `scripts/` in [docs/scripting.md](docs/scripting.md). Testing and trace in [docs/testing.md](docs/testing.md) and [docs/observability.md](docs/observability.md).
  133. ## What Migration Surfaces
  134. Migration exposes structural issues that were already present in the legacy skill — I/O mismatches, blurred function boundaries, ambiguous step definitions, and similar. That is expected, not a migration failure. Review the proposal, fix the contracts, add testcases, and the skill will run more reliably than before.
  135. Migration does not invent new problems — it makes existing ones visible.
  136. Monolithic skills often work despite implicit handoffs: step 2 assumes something step 1 "obviously" produces, boundaries between parsing and judgment are fuzzy, and shared rules are duplicated across sections. When you split into function contracts, those assumptions become explicit — and mismatches show up immediately.
  137. Common findings after migrate:
  138. - **I/O mismatch** — a downstream function expects fields that upstream does not output
  139. - **Blurred boundaries** — one legacy section maps to multiple functions, or one function owns too much
  140. - **Ambiguous definitions** — inputs and outputs described in prose, not stable object fields
  141. Treat these as migration output, not migration failure. Suggested follow-up:
  142. 1. Review `migration_proposal` and function contracts
  143. 2. Align pipeline I/O — rename fields, split or merge functions, add entries to `references/shared-glossary.md`
  144. 3. Run the skill once with trace enabled; export failing steps as testcases
  145. 4. Re-run tests until the pipeline is consistent
  146. Fixing these issues is the point of migration. A skill with explicit, tested function contracts hallucinates less and fails more predictably than a prose wall that only worked by accident.
  147. ## Repository Structure
  148. ```text
  149. skills/
  150. fskill-creator/ Create, maintain, or migrate functional skills
  151. sub-skills/
  152. create/ Form create_context from requirement brief
  153. migrate/ Form migration_context from a legacy skill directory
  154. docs/ Methodology and specifications
  155. templates/ Reusable skill templates
  156. examples/ Runnable functional skill examples
  157. ```
  158. ## Project Status
  159. Currently `v0.1.0 alpha`. File formats and script conventions are usable, but may still adjust before 1.0.
  160. This project does not bind to any agent platform, model vendor, or workflow engine. The built-in testcase runner is a runtime-agnostic assertion engine — it only validates output, does not execute agents or call models.
  161. ## Contributing
  162. Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development guide. For security-sensitive submissions, please read [SECURITY.md](SECURITY.md) first.
  163. ## License
  164. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.