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