What is skillstash-management?

This Claude skill provides a comprehensive framework for the lifecycle management of agentic skills within a standardized repository. It streamlines the development process by enforcing consistent directory structures, YAML metadata requirements, and automated validation rules, ensuring that agent instructions are high-quality, discoverable, and ready for deployment.

When should I use skillstash-management?

skillstash-management is useful in the following scenarios: • Standardizing Skill Creation: Use the structured templates and mandatory frontmatter to ensure all agent capabilities are consistently documented and easily indexed. • Automated Quality Assurance: Leverage the built-in validation scripts to enforce naming conventions, file constraints, and metadata integrity before merging changes. • Local-First Development: Implement a rapid iteration workflow that allows developers to create, save, and test skills locally with zero latency. • Collaborative Workflow Management: Follow standardized Git branch naming conventions and issue-driven workflows to manage multi-developer contributions to a skill library.

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

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.

Create skills/my-skill/SKILL.md
Save the file
The skill is now discoverable and usable
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

Start simple - Minimal viable skill, iterate to add features
Keep focused - One skill solves one problem well
Document clearly - Future you (or agents) will thank you
Test locally - Verify before pushing
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
---

skillstash-management

When & Why to Use This Skill

Use Cases