fp-refactor

Comprehensive guide for refactoring imperative TypeScript code to fp-ts functional patterns

Quality

52%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/fp-refactor/SKILL.md

Quality

Content

60%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill provides exceptionally actionable, executable code examples covering a comprehensive range of imperative-to-fp-ts refactoring patterns. However, it is severely over-long for a SKILL.md, explaining concepts Claude already knows (problems with try-catch, null, callbacks) and inlining content that should be split across multiple reference files. The 'When NOT to Refactor' section is a valuable addition but contributes to the overall verbosity.

Suggestions

Remove all 'The Problem with...' subsections — Claude already understands the drawbacks of try-catch, null checks, callbacks, and class-based DI. Replace with a single sentence if context is needed.

Split into multiple files: keep SKILL.md as a concise overview with the quick reference table and refactoring steps, then move detailed before/after examples into separate files like PATTERNS.md, PITFALLS.md, and ADOPTION.md.

Reduce before/after examples to one representative case per pattern instead of multiple variations — the current examples are repetitive (e.g., three separate fetch-related TaskEither examples).

Add explicit validation/verification steps to the refactoring workflow, such as 'Run existing tests to confirm behavioral equivalence after each function conversion.'

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~900+ lines. It extensively explains problems Claude already understands (e.g., 'The Problem with try-catch', 'The Problem with null/undefined', 'The Problem with Callbacks'), includes lengthy before/after examples that could be condensed, and repeats similar patterns multiple times. Many sections could be reduced to just the mapping table and key code snippets.	2 / 5
Actionability	Every pattern includes fully executable before/after TypeScript code with correct fp-ts imports, proper type annotations, and realistic use cases. The code is copy-paste ready and covers common cases including edge cases like error handling, parallel vs sequential execution, and bridge functions.	5 / 5
Workflow Clarity	Step-by-step refactoring guides are provided for key patterns (sections 1 and 2), and the gradual adoption strategies in section 8 provide a clear migration sequence. However, there are no explicit validation checkpoints or verification steps after refactoring (e.g., 'run tests to confirm behavior is preserved'), which is a minor gap for a refactoring workflow.	4 / 5
Progressive Disclosure	The entire skill is a monolithic document with no references to external files. At 900+ lines, the content would greatly benefit from splitting into separate files (e.g., patterns by category, pitfalls, adoption strategies). The table of contents helps navigation but doesn't compensate for the massive inline content.	2 / 5
	Total	13 / 20 Passed

Description

45%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear niche (fp-ts refactoring) but reads more like a document title than a skill description. It lacks specific actions, trigger guidance, and natural user keywords that would help Claude reliably select this skill from a large pool.

Suggestions

Add a 'Use when...' clause with trigger terms like 'fp-ts', 'functional programming', 'Either', 'Option', 'TaskEither', 'pipe', 'imperative to functional', or 'monadic patterns'.

List specific refactoring actions such as 'converts try/catch blocks to Either/TaskEither, replaces nullable values with Option, transforms imperative loops to functional pipelines using pipe and flow'.

Remove the word 'Comprehensive guide' framing and instead describe concrete capabilities in third person (e.g., 'Refactors imperative TypeScript code into fp-ts functional patterns...').

Dimension	Reasoning	Score
Specificity	Names the domain (TypeScript, fp-ts, functional patterns) and one concrete action (refactoring imperative code to functional patterns), but doesn't list specific refactoring operations like converting try/catch to Either, replacing loops with map/filter, or handling Option types.	3 / 5
Completeness	Has a vague 'what' (refactoring imperative TypeScript to fp-ts patterns) but completely lacks a 'when' clause. There is no 'Use when...' guidance, which per the rubric should cap completeness at 3, and the 'what' itself is more of a topic label than a clear capability statement.	2 / 5
Trigger Term Quality	Includes relevant keywords like 'TypeScript', 'fp-ts', 'functional patterns', 'imperative', and 'refactoring', but misses natural user phrases like 'functional programming', 'Either', 'Option', 'TaskEither', 'pipe', 'monads', or common variations users might say.	3 / 5
Distinctiveness Conflict Risk	The combination of 'fp-ts' and 'imperative TypeScript' refactoring is fairly niche and unlikely to conflict with general TypeScript or general refactoring skills. Minor overlap risk with broader functional programming or TypeScript refactoring skills.	4 / 5
	Total	12 / 20 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (1784 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/fp-refactor/SKILL.md
Commit: 57c135b

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.