---

name: skillstash-management description: How to create, validate, and manage skills in this skillstash instance

Skillstash Management

This skill tells you how to work with this repository. Use it whenever you need to create, modify, or manage skills.

When to Use This Skill

• Creating a new skill
• Modifying an existing skill
• Understanding the repo structure
• Running validation
• Pushing skills for review

Repository Structure

Copyskillstash/
├── skills/                    # All skills live here
│   └── my-skill/
│       ├── SKILL.md           # Required - skill definition
│       ├── references/        # Optional - docs, specs
│       ├── scripts/           # Optional - executable helpers
│       └── assets/            # Optional - templates, configs
├── .skillstash/
│   └── config.yml             # Skillstash configuration
├── docs/                      # Skillstash documentation
├── scripts/                   # Skillstash automation
└── .agents/                   # Agent instructions

Creating a Skill

1. Create the Directory

Copymkdir -p skills/my-skill-name

Use kebab-case for directory names.

2. Create SKILL.md

Every skill requires a SKILL.md with YAML frontmatter:

Copy---
name: my-skill-name
description: Brief one-line description of what this skill does
---

# My Skill Name

## When to Use This Skill

Describe trigger conditions.

## What This Skill Does

Step-by-step instructions.

## Examples

Concrete usage examples.

3. Required Frontmatter

4. Optional Frontmatter

Validation Rules

Skills must pass these checks:

Running Validation Locally

Copybun run validate

Local-First Workflow

Zero latency: Skills work immediately after saving.

1. Create skills/my-skill/SKILL.md
2. Save the file
3. The skill is now discoverable and usable
4. Iterate: edit, save, test, repeat

No git push required for local use.

Branch Naming Convention

Skill branches must follow this pattern:

The merge-readiness check enforces this. PRs with wrong branch names will fail.

Pushing for Permanence

When the skill works locally:

Copy# Create branch with correct naming
git checkout -b skill/add-my-skill

# Commit and push with Graphite
gt create -am "feat: add my-skill for [purpose]"
gt submit --no-interactive

Merge Readiness

PRs touching skills/** run the merge-readiness check which validates:

Once checks pass, enable auto-merge on the PR. It merges automatically when validation completes.

Optional Supporting Files

references/

External documentation, API specs, research notes.

Copyskills/my-skill/references/
└── api-docs.md

scripts/

Executable helpers for the skill.

Copyskills/my-skill/scripts/
└── setup.sh

assets/

Templates, images, configuration files.

Copyskills/my-skill/assets/
└── config-template.json

.research/

Temporary research notes. Removed before merge.

Issue-Driven Workflow

For tracked work, use beads:

Copy# Create issue
bd create --title="Create [skill-name] skill" --type=feature

# Claim work
bd update <id> --status=in_progress

# Implement skill (local-first)

# Close when done
bd close <id>
bd sync

Best Practices

1. Start simple - Minimal viable skill, iterate to add features
2. Keep focused - One skill solves one problem well
3. Document clearly - Future you (or agents) will thank you
4. Test locally - Verify before pushing
5. Under 500 lines - If longer, consider splitting

Common Issues

Skill Not Discovered

• Verify SKILL.md exists with frontmatter
• Check name field matches directory name
• Ensure directory is under skills/

Validation Fails

• Run bun run validate locally
• Check frontmatter YAML syntax
• Verify name is kebab-case
• Check line count (max 500)

Name Mismatch

Copy# Directory: skills/my-skill/
# Frontmatter must match:
---
name: my-skill  # Correct
name: mySkill   # Wrong - will fail validation
---