Purpose

This skill instructs AI agents on how to create new skills and add them to the shared skills repository at https://github.com/sourman/skills.

Repository Location

The skills repository is located at:

• Remote: https://github.com/sourman/skills
• Local working copy: /tmp/skills (or ~/skills in some environments)

Skill Structure

Each skill is a directory at the repository root containing a SKILL.md file:

skills/
├── skill-name-1/
│   └── SKILL.md
├── skill-name-2/
│   └── SKILL.md
└── README.md

The SKILL.md file must have:

1. YAML frontmatter with name and description
2. Markdown content with instructions for the AI agent

Creating a New Skill

Step 1: Navigate to the Repository

cd /tmp/skills
# OR if it doesn't exist:
git clone [email protected]:sourman/skills.git /tmp/skills
cd /tmp/skills

Step 2: Create the Skill Directory

mkdir <skill-name>

Use kebab-case for skill names (e.g., react-best-practices, typescript-eslint, docker-workflow).

Step 3: Create the SKILL.md File

Create <skill-name>/SKILL.md with the following structure:

---
name: skill-name
description: Brief one-line description of what this skill teaches the AI agent
---

# Skill Title

A clear, concise description of what this skill covers.

## What This Skill Covers

- Topic area 1
- Topic area 2
- Topic area 3

## Key Commands

Example commands relevant to this skill

command --option value

## Detailed Instructions

Provide detailed instructions, best practices, and workflows here.

## When to Use This Skill

Use this skill when:
- Condition 1
- Condition 2

Frontmatter Requirements:

• name: Must match the directory name (kebab-case)
• description: One-line summary for the skills directory

Step 4: Add and Commit to Git

# Ensure you're on the master branch
git checkout master

# Add the new skill
git add <skill-name>/

# Commit with a descriptive message
git commit -m "Add <skill-name> skill"

# If the master branch doesn't exist, you might be on main:
git checkout main

Step 5: Push to GitHub

# Push the changes
git push origin master
# OR if on main:
git push origin main

Example: Creating a New Skill

Here's a complete example of creating a skill called git-workflow:

# 1. Navigate to repo
cd /tmp/skills

# 2. Create directory
mkdir git-workflow

# 3. Create SKILL.md
cat > git-workflow/SKILL.md << 'EOF'
---
name: git-workflow
description: Git best practices, branching strategies, and commit conventions
---

# Git Workflow

This skill covers Git best practices for collaborative development.

## Branch Naming

Use descriptive branch names:
- `feature/add-user-authentication`
- `fix/login-page-bug`
- `refactor/database-connection`

## Commit Messages

Follow conventional commits:
- `feat: add user authentication`
- `fix: resolve login redirect issue`
- `docs: update API documentation`
EOF

# 4. Commit
git add git-workflow/
git commit -m "Add git-workflow skill"

# 5. Push
git push origin master

Updating an Existing Skill

To update an existing skill:

cd /tmp/skills

# Edit the skill file
vim <skill-name>/SKILL.md

# Commit and push
git add <skill-name>/SKILL.md
git commit -m "Update <skill-name> skill: describe changes"
git push origin master

Verifying the Skill

After pushing, verify the skill is accessible:

1. Check GitHub: https://github.com/sourman/skills/tree/main/<skill-name>;
2. Test installation in another project:

``bash bun x skills add sourman/skills/<skill-name> ``

Important Notes

1. Always use kebab-case for skill directory names
2. Frontmatter name must match the directory name
3. Write clear descriptions - this is what agents see when listing skills
4. Test your skill by installing it in a different project
5. Keep skills focused - each skill should cover a specific domain or technology

Troubleshooting

Git Push Fails

If push fails with "remote does not support password authentication":

# Ensure SSH is set up correctly
ssh -T [email protected]

Branch Name Issues

If you're not sure which branch you're on:

git branch
# Use 'main' or 'master' accordingly

Permission Denied

If you can't push:

1. Verify you have push access to sourman/skills
2. Check that you're authenticated as the correct user: gh auth status