Skills System

The Skills system connects you with a curated marketplace of reusable AI skills. Browse skills matched to your tech stack, install them with a single command, and customize them with learnings that improve over time.

Quick Start

Get recommendations based on your project:

Copy/agileflow:skill:recommend

Install a skill:

npmpnpmyarnbun
npx skills add vercel/next-skills
Copy

See what you have installed:

Copy/agileflow:skill:list

How It Works

Marketplace Discovery

AgileFlow includes a curated catalog of ~60 vetted skills across 6 categories:

Smart Recommendations

When you run /agileflow:skill:recommend, AgileFlow:

1. Detects your tech stack from package.json, requirements.txt, go.mod, and project files
2. Matches against curated skills by scoring tag overlap
3. Filters out already-installed skills from .claude/skills/
4. Shows ranked results with install commands

Live Marketplace

For broader discovery beyond curated picks:

npmpnpmyarnbun
npx skills search react        # Search by keyword
npx skills find                # Browse full marketplace
Copy

What Are Skills?

A skill is a structured prompt template that teaches Claude how to handle specific tasks in your project context. Skills are:

• Community-built - Created and maintained by the developer community on skills.sh
• Self-improving - Learn from your corrections via the learnings system
• Cookbook-based - Multiple use-case workflows in a single skill

Skill Structure

Each installed skill contains:

.claude/skills/<skill-name>/
├── SKILL.md              # Main skill file with instructions and triggers
├── references.md         # Links to docs, code patterns
└── cookbook/             # Per-use-case workflows
    ├── use-case-1.md
    └── use-case-2.md

How Skills Work

1. Activation: When you ask Claude about a topic matching a skill's triggers, the skill activates
2. Execution: Claude reads SKILL.md and follows the instructions
3. Learning: When you correct Claude, the skill learns your preferences
4. Evolution: Each correction updates the learnings file, making the skill smarter

Installing Skills

From Recommendations

Copy/agileflow:skill:recommend

This shows matching skills with install commands. Copy and run:

npmpnpmyarnbun
npx skills add vercel/next-skills
Copy

From Marketplace

Browse skills.sh directly:

npmpnpmyarnbun
npx skills search <keyword>
npx skills find
Copy

Manual Import

Copy a skill directory to your skills folder:

Copycp -r /path/to/skill .claude/skills/

The Learnings System

Skills can improve automatically through a learnings system:

.agileflow/skills/_learnings/
├── supabase-swift.yaml
├── api-client.yaml
└── react-components.yaml

What Skills Learn

When you use a skill and correct Claude's output, the skill learns:

1. Explicit corrections - High confidence learnings from direct feedback
2. Approved responses - Medium confidence learnings from approvals
3. Patterns - Low confidence observations for review

Learning File Format

Each skill has an optional learnings file at .agileflow/skills/_learnings/<skill>.yaml:

Copyskill: supabase-swift
version: 1
last_updated: 2025-01-08T10:30:00Z
 
preferences:
  code_style: "swift-concurrency"
  error_handling: "Result<T, Error>"
 
conventions:
  naming: "camelCase for variables, PascalCase for types"
  testing: "Unit tests required for all public APIs"
 
anti_patterns:
  - "Avoid callback patterns (use async/await instead)"
  - "Never hardcode API keys in code"
 
metadata:
  corrections_count: 12
  approvals_count: 8

How Self-Improvement Works

On invocation:

1. Claude checks if a learnings file exists
2. Reads preferences, conventions, and anti-patterns
3. Applies them while executing the skill

On correction:

1. You provide feedback or correction
2. Claude extracts the signal (what to change)
3. Updates the learnings file
4. Next invocation uses the updated preferences

Best Practices

Choosing Skills

1. Start with recommendations - Run /agileflow:skill:recommend first
2. Match your stack - Skills work best when they match your actual technologies
3. One domain per skill - Focused skills are more effective than broad ones
4. Check quality - Review the skill's SKILL.md before using it extensively

Maintaining Skills

1. Review learnings - Check what the skill learned from corrections
2. Update references - Keep documentation links current
3. Archive unused skills - Clean up skills you no longer use
4. Share improvements - Commit learnings to git for team consistency

Sharing Skills

Version Control

Commit skills and learnings to git:

Copygit add .claude/skills/
git add .agileflow/skills/_learnings/
git commit -m "Add next-best-practices skill with learnings"

Team members automatically get the skill and learnings.

Creating Custom Skills

You can create your own skills manually:

1. Create a directory in .claude/skills/<skill-name>/
2. Add a SKILL.md with frontmatter (name, description)
3. Optionally add references.md and cookbook/ entries
4. The skill will appear in /agileflow:skill:list

Troubleshooting

Skill Not Activating

1. Check the "When to Use" section in SKILL.md
2. Make sure your question matches the activation triggers
3. Edit the skill to add more keywords if needed

Learnings File Missing

1. Create the learnings file at .agileflow/skills/_learnings/<skill>.yaml
2. Future corrections will be tracked automatically

Related Commands

• /skill:list - View installed skills and marketplace recommendations
• /skill:recommend - Get personalized skill recommendations for your tech stack