🧰 blkst8/skills

A personal arsenal of agent skills — small, opinionated, load-bearing.

Each skill is a single, composable SKILL.md you can drop into any agent harness that supports progressive-disclosure instructions.

---

✨ What is this?

This repository is my personal collection of agent skills — self-contained SKILL.md files that teach AI agents a specific workflow, convention, or behavior. They are:

• Bounded. One skill = one job. No kitchen-sink prompts.
• Composable. Skills stack. A brainstorm recommendation can be sent through spec-review; self-healing runs underneath every task.
• Harness-agnostic. Any agent that loads SKILL.md can use them.
• Installable everywhere. A single shell script publishes them globally and to every git repo on your machine.

Think of this repo as a toolbox. Pull only the SKILL.md you need; ignore the rest.

---

🎯 The Skills

Skill	What it does	Always-on?
trump	Binary emphasis layer — CRITICAL concepts in ALL CAPS, with a live PRIORITY REGISTER that survives every step of reasoning.	✅
self-healing	Six-phase improvement cycle (Observe → Reflect → Extract → Score → Generate → Register) that turns repeated patterns into new skills automatically.	✅
brainstorm	Evaluate a developer's engineering problem against four measurements (complexity, dependency, maintainability, extendability) from MVP and Quality perspectives, then recommend the best approach with a rate out of 5.	—
spec-review	Interactive review of an agent-spec .md file: one validation question at a time, answered with y / n / tell you correct way — applies corrections only after the user confirms.	—
feature-manager	Decompose a markdown feature spec into a structured roadmap of goals + tasks, written to a versioned /tmp/ checklist.	—
go-codebase-style	Generate, scaffold, and review Go code following the blkst8 layered architecture (handlers → usecase → repository/service), with Echo, zap, Viper, sqlx, workers, and both Global-Singleton and Private-DI wiring.	—

The six skills, in one breath

• trump makes sure the agent never loses sight of what matters.
• self-healing makes sure the agent gets better every time it runs.
• brainstorm makes sure the right approach gets picked before code is written.
• spec-review makes sure the agent does what you actually meant.
• feature-manager makes sure big ideas become small, shippable tasks.
• go-codebase-style makes sure every line of Go matches the house style.

---

🏗️ Anatomy of a Skill

Every skill in this repo follows the same minimal shape:

skills/<name>/
├── SKILL.md            # the only required file
├── evals/              # (optional) trigger & behavior evals
├── references/         # (optional) deeper theory, tables, history
└── assets/             # (optional) files used in output (templates, icons)

SKILL.md opens with a YAML frontmatter block that drives discovery:

---
name: skill-name
description: >
  Plain-language trigger conditions. When should this skill fire?
  Which phrases, file types, and user intents should activate it?
---

A good skill is specific about when to fire and rigorous about how to behave. The six in this repo model that.

---

⚡ Installation

Want only one skill? Copy a single directory:

cp -r skills/feature-manager ~/.agents/skills/

---

🧩 Companion Skills (not in this repo)

These are skills I use daily that live elsewhere. See other-skills.md for install snippets.

• ast-grep — structural code search for refactors and codemods.
• caveman — token-saving compressed communication mode.
• goalbuddy — structured goal intake for long-running Claude Code work.

---

📚 Specs & Theory

Long-form thinking that backs the skills lives in specs/:

File	Topic
BRAINSTORM	The two-path (MVP / Quality) approach-recommendation algorithm.
AI Spec – Self-Improving Agent	Full theory of the self-healing six-phase cycle.
CAPS Emphasis Agent Skill — Spec	Design notes for the binary-emphasis pattern.
Feature-manager	The decomposition heuristics behind feature-manager.
GO_CODEBASE_STYLE / GUIDE	Go conventions for any agent touching Go codebases — implemented by the go-codebase-style skill.
standard-contractions-and-informal	Voice rules for terse, human-feeling output.

---

🛠️ Authoring Your Own

The fastest path:

1. Copy any skills/<name>/ directory.
2. Rewrite the frontmatter description to be specific about trigger conditions.
3. Write the body in three parts: When to use / When NOT to use / Algorithm.
4. Add at least one eval under evals/ to lock the trigger phrase.
5. Open a PR.

The skills in this repo are the same shape you'd ship.

🤝 Contributing

Issues and PRs welcome — but read spec-review first. It will save you a round trip.

📄 License

MIT — do what you want, just keep the attribution.

_{Built and maintained by @blkst8. If a skill here saved you a debugging session, star the repo ⭐.}