f-skill

F does not stand for fail. It doesn't stand for FF instant noodle either (just kidding). F is for Frontend. 🍜

Welcome to f-skill — a repository of battle-tested, opinionated frontend skills designed for AI coding agents. This package is fully compatible with the Agent Skills open standard and works seamlessly with tools like VS Code Copilot, Claude Code, Gemini CLI, Cursor, and Windsurf.

---

📦 Installation

To equip your AI agent with these skills, run the following command in your project directory:

npx skills add ReiiYuki/f-skill

This will download the skills into your .agents/skills folder, making them immediately discoverable by your AI assistant.

🛠️ Available Skills

Skill	Description
f-skill-workflow	Universal Meta-Skill. A single entrypoint you can invoke to tell the agent to build or refactor a feature using the entire f-skill ecosystem.
component-design	Design and structure UI components using a 7-tier responsibility system with strict naming conventions and callback patterns. Framework-agnostic (React, Flutter, etc.).
testing-convention	Framework-agnostic testing philosophy and decision matrix. Guides on unit vs integration vs e2e, component test structure (Visuals/Lifecycle/Interactions), and human-readable documentation.
module-architecture	Organize project structure using a flat, module-based architecture where business features and technical concerns are equal peers. Covers internal folder structure, cross-module boundaries, and origin-based ownership.
script-creation	Conventions for writing functions, scripts, and utilities. Covers single function per file, object parameter patterns, documentation requirements, mapper patterns, logic splitting, and co-located tests.
state-management	Framework-agnostic decision matrix for choosing the right state management approach. Maps state types to 4 architectural tiers: Local Component State, Subtree State, Server State Cache, and Global State.
feature-breakdown	Orchestrator Skill. Teaches the agent how to plan and slice a large feature into smaller subtasks, mapping each subtask to the other 5 execution skills in a specific dependency order.
project-bootstrap	Day-Zero Skill. Mandatory infrastructure setup rules (Linting, Security Guardrails, Testing, Config Handling, Version Control) before any code is written.

🧬 Agent Orchestration Workflow

When an AI agent is asked to build a new project or a large feature, it uses these orchestration skills:

graph TD
    M[User Request: Universal f-skill-workflow] -->|Routes to Orchestrators| Z
    M --> A
    
    Z[User Request: New Project] --> Y{project-bootstrap}
    Y -->|Must Configure First| X(Lint, Security, Test, Config, Versioning)
    X --> A
    
    A[User Request: Build Feature] --> B{feature-breakdown}
    B -->|Step 0: Discovery| C0(Find Existing Code)
    C0 --> C(module-architecture)
    B -->|Step 1: Setup Modules| C
    B -->|Step 2: Data Flow| D(state-management)
    B -->|Step 3: APIs & Logic| E(script-creation)
    B -->|Step 4: Component & Composition| F(component-design)
    B -->|Step 5: Verification| G(testing-convention)

Loading

🧠 Philosophy

These skills capture opinionated, battle-tested frontend patterns that apply across modern component-based frameworks. They are built on five core pillars:

1. Compatibility First: Agents must prioritize an existing codebase's rules over f-skill conventions. These skills adapt to your legacy code, they don't fight it.
2. Framework-Agnostic: The principles work whether you are writing React, Flutter, Vue, or any other component-based UI system.
3. Responsibility-Driven: We focus on what a component should do, not arbitrary metrics like line counts.
4. Analytics-Ready: Every action exposes callbacks for seamless integration with tracking and analytics tools.
5. Type-Safe & Scalable: Data is passed as domain objects, utilizing bounded generics for maximum reusability.

🤖 How Agents Use These Skills

Once installed, your AI agent will automatically read the YAML frontmatter of these skills to understand its new capabilities. The true power of f-skill lies in the synergy between these skills.

Here are common scenarios and the prompts you can use to trigger the optimal agent workflow:

Scenario 1: Starting a Brand New Project (Day Zero)

You want to ensure the agent doesn't write spaghetti code on day one.

Prompt: "Initialize a new Next.js / Flutter project in this directory. Before writing any app code, make sure you follow the project-bootstrap skill to set up our foundational infrastructure."

Agent Action: The agent will immediately configure the Linter, Prettier, Husky hooks, Gitleaks, Testing framework, and centralized Typed Config before moving on to feature development.

Scenario 2: Building a Large Feature from Scratch

You have a complex requirement and want the agent to architect it properly.

Prompt: "We need to build a new 'Checkout' flow. Please use the feature-breakdown skill to analyze this and present a subtask plan before you start coding."

Agent Action: The agent stops, creates a dependency-ordered plan (Module Setup ➡️ State Management ➡️ API Scripts ➡️ Component Composition ➡️ Testing), and waits for your approval.

Scenario 3: Deciding Where Data Belongs

You are unsure if you need Redux/Riverpod or just local state.

Prompt: "I need to store the user's selected language, but it affects the whole app. Check the state-management decision matrix and tell me where this state should live."

Agent Action: The agent reads the matrix, identifies this as a "Tier 4: Global / App-Wide State" requirement, and suggests using Zustand, Redux, or Provider.

Scenario 4: Refactoring a Giant Component

An existing component is 500+ lines and doing too much.

Prompt: "Refactor this giant 500-line UserProfile widget. Use the responsibility tiers from the component-design skill to split it up into Presentational, Container, and Controller components."

Agent Action: The agent strips API calls out of the UI, creates pure visual components with callback props, and wraps them in a logic-handling Container.

Scenario 5: Standardizing Tests

You want high-quality tests that act as documentation.

Prompt: "I'm going to write tests for the login component. Let's use our testing-convention to structure the describe blocks."

Agent Action: The agent generates tests formatted specifically with describe('Case: ...') and nests them into Visuals, Lifecycle, and Interactions.

Scenario 6: Reusing Code & Design Systems

You want to ensure the agent doesn't hallucinate custom UI elements.

Prompt: "Create a warning banner for the dashboard. Use our component-design and feature-breakdown skills."

Agent Action: The agent performs a Discovery Phase to find existing Warning Banner components. If the requested design differs from the Design System, it will push back and ask you to consult the UX/UI designer rather than writing custom inline CSS.

Scenario 7: Preventing Edge-Case Bloat

You ask for a feature that is too complex for a single flow.

Prompt: "Build an authentication flow that handles Guests, Email Users, OAuth Users, and Enterprise SSO. Follow script-creation and feature-breakdown." Agent Action: Triggering the Complexity Pushback rule, the agent refuses to build a single "God Function". It pushes back, asking to split the requirements into 4 distinct, manageable sub-flows.

Scenario 8: The Universal "One Command" Trigger

You want the agent to use all f-skill conventions without manually listing them out.

Prompt: "Build a Shopping Cart feature using the f-skill-workflow."

Agent Action: The agent reads the meta-skill, refuses to write code immediately, and delegates the entire prompt to feature-breakdown. It then automatically cascades through Discovery, Planning, module-architecture, state-management, script-creation, component-design, and testing-convention to deliver the feature perfectly.

🤝 Contributing

We welcome contributions! If you have a robust frontend pattern you'd like to codify into a skill:

1. Fork the repository.
2. Create a new directory for your skill (e.g., state-management).
3. Add a SKILL.md file following the Agent Skills standard (include name and description in YAML frontmatter).
4. Keep instructions concise, under 500 lines, and strictly professional in the body.
5. Submit a Pull Request!

📄 License

This project is licensed under the MIT License.