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

| Field | Description | | ----- | ----------- | | name | Must match directory name exactly (kebab-case) | | description | One-line summary for discovery |

4. Optional Frontmatter

| Field | Description | | ----- | ----------- | | version | Semver (e.g., 1.0.0) | | author | GitHub username | | tags | Array for categorization | | status | experimental, stable, deprecated |

Validation Rules

Skills must pass these checks:

| Rule | Requirement | | ---- | ----------- | | SKILL.md exists | Required file in skill directory | | Valid frontmatter | YAML must parse, required fields present | | Name matches | name field must equal directory name | | Kebab-case | Directory name: lowercase, hyphens only | | Max 500 lines | Keep skills focused and maintainable |

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:

| Pattern | Use case | | ------- | -------- | | skill/add-<slug> | Creating a new skill | | skill/update-<slug> | Modifying an existing skill | | skill/remove-<slug> | Deleting a skill |

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:

| Check | Blocking | | ----- | -------- | | Branch naming (skill/*) | Yes | | Required labels exist | No (warning) | | Auto-merge enabled | No (warning) | | Merge settings correct | No (warning) |

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