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

skillstash/
├── 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

mkdir -p skills/my-skill-name

Use kebab-case for directory names.

2. Create SKILL.md

Every skill requires a SKILL.md with YAML frontmatter:

---
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

bun 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:

# 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.

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

scripts/

Executable helpers for the skill.

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

assets/

Templates, images, configuration files.

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

.research/

Temporary research notes. Removed before merge.

Issue-Driven Workflow

For tracked work, use beads:

# 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

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