Skip to Content
TutorialsCreate Your First Skill

Create Your First Skill

Skills package reusable expertise into discoverable capabilities. In this tutorial you will write a skill that enforces your team’s commit message convention, then share it via git.

Prerequisites

Step 1: Create the skill directory

Skills live in a directory containing a SKILL.md file.

Personal skill (available in all your projects):

mkdir -p ~/.proto/skills/commit-message

Project skill (shared with teammates via git):

mkdir -p .proto/skills/commit-message

Use the project location for this tutorial so you can commit and share it.

Step 2: Write SKILL.md

Create .proto/skills/commit-message/SKILL.md:

---
name: commit-message
description: Writes conventional commit messages. Use when committing changes, writing a commit, or asked to summarise what changed.
---
 
# Commit Message Skill
 
Write commit messages using the Conventional Commits format:

():

[optional body]

[optional footer]


## Types

| Type | When to use |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `test` | Adding or correcting tests |
| `chore` | Build, tooling, or config changes |

## Rules

- Summary line ≤ 72 characters
- Use imperative mood: "add" not "added" or "adds"
- Do not end the summary with a period
- Reference issue numbers in the footer: `Closes #123`

## Example

feat(auth): add OAuth2 PKCE flow for CLI clients

Replaces the implicit grant flow which is deprecated. The PKCE verifier is generated per-session and never persisted.

Closes #456

The description field is what proto uses to decide when to invoke this skill — make it specific.

Step 3: Test the skill

Start a session and make some changes, then ask:

commit my changes

proto will recognise the commit intent, load the skill, and produce a properly formatted message.

You can also invoke it explicitly:

/skills commit-message

Use autocomplete (Tab) to browse available skills.

Step 4: Share with your team

git add .proto/skills/commit-message/
git commit -m "chore: add commit-message skill for team conventions"
git push

Teammates automatically get the skill the next time they pull.

Debugging

If proto does not pick up the skill automatically:

  • Check the description — it should mention keywords users will naturally say (“commit”, “commit message”, “summarise changes”)
  • Check the file path — must be SKILL.md (not skill.md) inside a named directory
  • Check YAML syntax — the frontmatter must open on line 1 with --- and close with ---
head -5 .proto/skills/commit-message/SKILL.md

What to try next

Add a reference file — put detailed examples in a reference.md alongside SKILL.md and link to it from the instructions.

Add a script — drop a helper script in scripts/ and call it from the skill instructions.

Compose skills — proto can load multiple skills per session. Build a library of focused skills that combine naturally.

Reference

Last updated on
Build Your First Sub-Agent