How to Contribute New Skills to the Flutter Skills Repository: A Step-by-Step Guide

To contribute new skills to the Flutter skills repository, file a GitHub issue describing the proposed workflow, wait for maintainer triage and approval, then submit a pull request containing a properly structured SKILL.md file inside a new folder under skills/.

The Flutter skills repository hosts reusable, high-level workflows for common Flutter development tasks. Each skill is a self-contained package that agents can execute to perform specific tasks like configuring routing or adding widget tests. Contributing new skills requires understanding the repository's architecture and following the contribution protocol defined in CONTRIBUTING.md.

Understand the Repository Structure

Before you contribute, familiarize yourself with how skills are organized in the source tree.

Skill Organization

Each skill lives in a dedicated folder under skills/ containing exactly one SKILL.md file. For example, the flutter-use-http-package skill resides at skills/flutter-use-http-package/SKILL.md. This file combines YAML front matter with instructional markdown that defines the workflow.

Key Configuration Files

The repository maintains strict quality standards through several core files:

• CONTRIBUTING.md – Defines the issue filing process, triage workflow, and acceptance criteria.
• README.md – Contains the master index table of all available skills that you must update when adding new entries.
• tool/dart_skills_lint/ – Houses the custom lint package that validates SKILL.md formatting and structure.

Step-by-Step Contribution Workflow

The Flutter skills repository uses an issue-first contribution model to ensure proposed skills align with project goals.

1. Check the Public Backlog

Before proposing a new skill, verify that your idea isn't already planned. The maintainers track upcoming skills in issue #88 in the GitHub tracker. Review this backlog to avoid duplicate proposals.

2. Create a Detailed GitHub Issue

If your skill isn't listed, open a new issue with the title format Add skill: <skill-name>. According to CONTRIBUTING.md, the issue must include:

• A concise title and description of the problem the skill solves.
• The target language model (e.g., gemini-3.1-pro-preview, claude-sonnet-4.6).
• Relevant logs or example prompts demonstrating the desired agent behavior.

3. Wait for Maintainer Triage

Maintainers will review your proposal, add a triaged label, and assign a priority level (P0 through P3). The triage process description in CONTRIBUTING.md explains that only approved issues should proceed to implementation.

4. Submit Your Pull Request

Once approved, implement your skill following this workflow:

# Fork and clone the repository

git clone https://github.com/<your-username>/skills.git
cd skills

# Create the skill directory

mkdir -p skills/<skill-name>

# Copy the template scaffold

cp template/SKILL.md skills/<skill-name>/SKILL.md

# Edit the SKILL.md file with your content

# Then commit and push

git add skills/<skill-name>/SKILL.md
git commit -m "Add <skill-name> skill"
git push origin <branch-name>

# Open a pull request against the main repository

Update the README.md skill index table to include your new entry with the Skill name, Description, and Example prompt columns.

Crafting the SKILL.md File

The SKILL.md file is the canonical definition of your contribution. It must follow the exact format used by existing skills like flutter-use-http-package.

YAML Front Matter Requirements

Every SKILL.md must begin with YAML front matter enclosed in triple dashes:

---
name: flutter-add-custom-theme
description: Add a reusable ThemeData definition and apply it to MaterialApp.
metadata:
  model: models/gemini-3.1-pro-preview
  last_modified: Fri, 10 May 2026 12:00:00 GMT
---

The name field must match the folder name exactly.

Required Content Sections

Following the front matter, include these standard sections:

1. Overview – Brief explanation of what the skill accomplishes.
2. Configuration & Permissions – Any prerequisites or setup requirements.
3. Request Execution – How the agent should interpret and execute commands.
4. Workflow – Step-by-step implementation instructions.
5. Examples – Runnable code samples demonstrating the skill output.

Documentation Standards

When writing instructional content, use clear ATX-style headings and ensure all Dart code blocks specify the language identifier. The linting rules in tool/dart_skills_lint/CONTRIBUTING.md enforce formatting consistency across all skill files.

Validate and Test Your Skill

Although the repository does not currently run automated tests on skill files, you must manually verify functionality. Run the skill using the CLI:

npx skills add flutter/skills --skill '<skill-name>'

Test the generated code in a fresh Flutter project to ensure it compiles and behaves as documented. Verify that your markdown passes the custom lint rules defined in tool/dart_skills_lint/README.md.

Summary

• Check issue #88 before proposing new skills to avoid duplicates.
• File a GitHub issue first with the target model and use case description.
• Wait for triage and priority assignment (P0-P3) before implementing.
• Create a SKILL.md with proper YAML front matter in skills/<skill-name>/.
• Update README.md to include your skill in the public index table.
• Test manually using the skills CLI to ensure the workflow executes correctly.

Frequently Asked Questions

What is the exact file structure for a new skill?

Create a folder under skills/ named after your skill identifier (e.g., skills/flutter-add-custom-theme/) containing exactly one file: SKILL.md. This file must include YAML front matter with name, description, and optional metadata fields, followed by markdown content describing the workflow.

Can I submit a pull request without opening an issue first?

No. According to the CONTRIBUTING.md guidelines, you must open a GitHub issue for triage before submitting code. Maintainers assign priorities and approve concepts before implementation begins.

How do I know which language model to specify in the metadata?

Specify the model you tested against or designed the skill for, such as models/gemini-3.1-pro-preview or claude-sonnet-4.6. If the skill works across multiple models, note the primary target or use the metadata section to list compatible versions.

Does the repository have automated checks for new skills?

Yes. The tool/dart_skills_lint/ package contains linting rules that validate SKILL.md formatting. While these enforce structural consistency, you must manually verify that the skill instructions actually work by running them against a real Flutter project.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}