Refactor skill documentation: consolidate SKILL.md, add reference docs

AGENTS.md

@@ -27,9 +27,9 @@ plugin-name/
 │   └── helper.md
 ├── skills/                      # Agent Skills — both tools (SKILL.md format is shared)
 │   └── my-skill/
-│       ├── SKILL.md
-│       ├── PRINCIPLES.md
-│       └── EXAMPLES.md
+│       ├── SKILL.md             # ≤100 lines; see Skill Authoring Conventions
+│       ├── reference.md         # overflow detail, linked one level deep
+│       └── templates/
 ├── hooks/                       # Event hooks (Claude Code format)
 │   └── hooks.json
 ├── .mcp.json                    # MCP servers (Claude Code format)
@@ -131,8 +131,26 @@ codex plugin marketplace upgrade devstefancho-claude-plugins
 
 **Skills** (`skills/<skill-name>/SKILL.md`)
 - Required `SKILL.md` with metadata frontmatter and instructions.
-- Optional supporting files (`PRINCIPLES.md`, `EXAMPLES.md`, `scripts/`, `references/`).
-- Auto-loaded by both tools when relevant context is detected.
+- Optional supporting files (`reference.md`, `templates/`, `scripts/`, `references/`).
+- Auto-loaded by both tools when relevant context is detected, and installable standalone via `npx skills add devstefancho/claude-plugins`.
+- Must follow the Skill Authoring Conventions below.
+
+### Skill Authoring Conventions
+
+Skills follow the style of [mattpocock/skills](https://github.com/mattpocock/skills). When creating or editing a skill:
+
+**Frontmatter**
+- `name` (required): kebab-case, must match the skill directory name. Never rename casually — it is the installed-skill identity.
+- `description` (required): single line, third person, two-sentence pattern — first what the skill does, then `Use when [explicit triggers]` listing literal phrases users say (keep Korean trigger phrases like 스펙 생성, 팀 만들어줘). Max 1024 chars.
+- **The description must be valid YAML.** A bare colon inside an unquoted value breaks parsing and silently hides the skill from `npx skills` and frontmatter-driven discovery — wrap the value in double quotes if it contains `:`. `scripts/validate-plugins.sh` enforces this.
+- Claude-specific fields (`allowed-tools`, `context`, `agent`, `model`, `effort`, `user-invocable`) are allowed; other agents ignore them.
+- Internal-only skills add `metadata.internal: true` so `npx skills` hides them from discovery.
+
+**Body**
+- `# Title` then short `##` sections. Terse, imperative, opinionated. Bold the hard rules.
+- Use numbered phases for workflows and `- [ ]` checklists as gates between phases.
+- Add an Anti-patterns section with WRONG/RIGHT contrast where the skill has known failure modes.
+- Keep `SKILL.md` under ~100 lines. Move overflow into sibling `.md` files in the same skill directory, linked one level deep (`See [reference.md](reference.md)`). Never delete behavior-critical detail — relocate it.
 
 **Subagents** (`agents/*.md`)
 - One Markdown file per subagent.
@@ -169,6 +187,7 @@ What it verifies:
 - `.claude-plugin/marketplace.json` and `.agents/plugins/marketplace.json` list the same plugin names.
 - Each Codex marketplace entry uses the correct schema: `source.source = "local"`, `source.path` matches the Claude side, `policy.installation` ∈ {`AVAILABLE`, `NOT_AVAILABLE`, `INSTALLED_BY_DEFAULT`}, `policy.authentication` ∈ {`ON_INSTALL`, `ON_USE`}, and `category` is non-empty.
 - Every `AVAILABLE` Codex plugin actually has at least one Codex-loadable component (`skills/`, `agents/`, `.app.json`, or `codex.config.toml.snippet`).
+- Every `skills/*/SKILL.md` has parseable YAML frontmatter with non-empty `name` (matching its directory) and `description` (≤1024 chars). This catches the unquoted-colon bug that hides skills from `npx skills` discovery (requires `python3`; YAML parse check additionally requires PyYAML).
 
 Run this before pushing any change that touches manifests or the marketplace catalog. A failing run almost always means one of the paired files was edited without the other.
 
@@ -195,8 +214,9 @@ Recommended workflow when adding or removing a marketplace entry:
 Plugins are shared via:
 
 1. **Git Repository** — both tools support GitHub shorthand (`<owner>/<repo>`).
-2. **Local Development** — point the tool's marketplace at a local path.
-3. **Team Configuration** — use `.claude/settings.json` for Claude Code; Codex records configured marketplaces in `~/.codex/config.toml` after `codex plugin marketplace add`.
+2. **`npx skills`** — the [skills CLI](https://github.com/vercel-labs/skills) discovers every skill in this repo through `.claude-plugin/marketplace.json` and installs them into 70+ agents: `npx skills add devstefancho/claude-plugins`. Skill-only distribution — commands, hooks, and MCP servers still require a plugin install.
+3. **Local Development** — point the tool's marketplace at a local path.
+4. **Team Configuration** — use `.claude/settings.json` for Claude Code; Codex records configured marketplaces in `~/.codex/config.toml` after `codex plugin marketplace add`.
 
 ## See Also
 

README.md

@@ -4,6 +4,26 @@ A collection of reusable plugins for AI coding agents — slash commands, agent
 
 ## Quick Start
 
+### Any agent — `npx skills` (recommended)
+
+Skills in this repo install into 70+ agents (Claude Code, Codex, Cursor, Copilot, ...) via the [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+# Interactive: pick skills + target agents
+npx skills add devstefancho/claude-plugins
+
+# List available skills without installing
+npx skills add devstefancho/claude-plugins --list
+
+# Install one skill non-interactively
+npx skills add devstefancho/claude-plugins --skill writing-specs -a claude-code -y
+
+# Install everything to all detected agents
+npx skills add devstefancho/claude-plugins --all
+```
+
+`npx skills` installs the skill content only. To get slash commands, hooks, and MCP servers too, install the full plugin through Claude Code or Codex below.
+
 ### Claude Code
 
 ```bash
@@ -60,6 +80,16 @@ codex plugin marketplace add devstefancho/claude-plugins
 | [session-resume-plugin](./session-resume-plugin) | Yes | Yes | Resume work from a previous Claude Code or Codex CLI session by reading the last N turns from its JSONL transcript |
 | [stop-notification-plugin](./stop-notification-plugin) | Yes | No | Claude Code hook-based macOS TTS notification when Claude stops or needs attention |
 
+## Skill Style
+
+Every skill follows the same conventions (inspired by [mattpocock/skills](https://github.com/mattpocock/skills)):
+
+- Frontmatter `description` is two sentences: what it does, then `Use when [explicit triggers]`.
+- `SKILL.md` stays under ~100 lines — terse, imperative, with phase workflows and checklist gates.
+- Overflow detail lives in sibling files (`reference.md`, `templates/`, `scripts/`), linked one level deep.
+
+See the Skill Authoring Conventions section in [`AGENTS.md`](./AGENTS.md) before adding or editing a skill.
+
 ## Plugin Structure
 
 Each plugin ships parallel manifests. Plugins marked as Codex-compatible include Codex-loadable components such as skills:

agent-team-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-team-plugin",
   "description": "Agent team management - create, expand, and cleanup teams for worktree sessions",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "author": {
     "name": "Stefan Cho"
   }

agent-team-plugin/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-team-plugin",
   "description": "Agent team management - create, expand, and cleanup teams for worktree sessions",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "skills": "./skills/",
   "author": {
     "name": "Stefan Cho"

agent-team-plugin/skills/create-team/SKILL.md

@@ -1,74 +1,57 @@
 ---
 name: create-team
-description: Create an agent team with planner and implementer teammates for spec-driven development. Use when user says "create team", "팀 생성", "팀 만들어줘", "agent team", or wants to set up a planner+implementer workflow in a worktree session.
+description: Creates a planner + implementer agent team for the current worktree session. Use when user says "create team", "팀 생성", "팀 만들어줘", "agent team", or wants a planner+implementer spec-driven workflow in a worktree session.
 effort: medium
 allowed-tools: Bash, Agent, SendMessage, TeamCreate, TaskCreate, TaskList, TaskUpdate, Read, AskUserQuestion
 ---
 
 # Create Team
 
-Creates a planner + implementer agent team for the current worktree session.
+Spin up a planner + implementer agent team for the current worktree session.
 
-## Workflow
+## Phase 1 — Derive the team name
 
-### Step 1: Determine team name
+Run `git branch --show-current`, then convert to kebab-case:
 
-Run `git branch --show-current` to get the current branch name. Convert to kebab-case team name:
-- Remove `worktree-` prefix if present
+- Strip a `worktree-` prefix
 - Replace `+` with `-`
 - Example: `worktree-feat+electron-app` → `feat-electron-app`
 
-### Step 2: Create the team
+## Phase 2 — Create the team
 
-Call `TeamCreate` with:
-- `team_name`: the derived team name
-- `description`: "Planner + Implementer team"
+Call `TeamCreate` with `team_name` = derived name, `description` = "Planner + Implementer team".
 
-### Step 3: Spawn teammates (parallel)
+## Phase 3 — Spawn teammates in parallel
 
-Spawn both teammates **in parallel** using the Agent tool in a single message with two tool calls:
+**One message, two Agent tool calls.** Both with the team name and `run_in_background: true`.
 
-**Planner:**
-- `team_name`: the team name
-- `name`: "planner"
-- `description`: "Planner - brainstorm and spec writing"
-- `prompt`: Read the full content of [templates/planner-prompt.md](templates/planner-prompt.md) and pass it as the prompt
-- `run_in_background`: true
+- **planner** — description "Planner - brainstorm and spec writing"; prompt = full content of [templates/planner-prompt.md](templates/planner-prompt.md)
+- **implementer** — description "Implementer - code and test writing"; prompt = full content of [templates/implementer-prompt.md](templates/implementer-prompt.md)
 
-**Implementer:**
-- `team_name`: the team name
-- `name`: "implementer"
-- `description`: "Implementer - code and test writing"
-- `prompt`: Read the full content of [templates/implementer-prompt.md](templates/implementer-prompt.md) and pass it as the prompt
-- `run_in_background`: true
+## Phase 4 — Loop setup
 
-### Step 4: Loop setup
+Send via SendMessage:
 
-Send loop configuration via SendMessage:
-- To "planner": If `/writing-specs` skill is available, "Run `/loop 10m /writing-specs update spec` to periodically check and update specs." Otherwise skip this loop setup.
-- To "implementer": "After completing assigned work, check TaskList for new tasks. You can run `/loop 10m check TaskList for unassigned tasks and report to team-lead` to automate this."
+- To **planner** — only if the `/writing-specs` skill is available: "Run `/loop 10m /writing-specs update spec` to periodically check and update specs." Otherwise skip.
+- To **implementer**: "After completing assigned work, check TaskList for new tasks. You can run `/loop 10m check TaskList for unassigned tasks and report to team-lead` to automate this."
 
-### Step 5: Display work guide
+## Phase 5 — Display the work guide
 
-Read [templates/work-guide.md](templates/work-guide.md) and display the content to the user.
-Teammate colors are auto-assigned from a hardcoded palette and cannot be configured programmatically.
+Read [templates/work-guide.md](templates/work-guide.md) and display it to the user.
 
-## Fallback
+## Fallback — teammate spawning fails
 
-If teammate spawning via the Agent tool fails with `team_name` or another internal error in the current session (known issue anthropics/claude-code#40270):
-1. Inform the user that team creation succeeded but teammate spawning failed in the current execution context
-2. Suggest spawning teammates manually:
-   - Open separate terminal windows
-   - Run `claude` in each with the planner/implementer prompts
-   - Use SendMessage for coordination
-3. Do not claim the Agent tool is globally unavailable unless the session explicitly shows that tool is missing
+If the Agent tool fails with a `team_name` or other internal error in the current session (known issue anthropics/claude-code#40270):
 
-## Notes
+1. Tell the user team creation succeeded but teammate spawning failed in this execution context.
+2. Suggest manual spawning: open separate terminals, run `claude` in each with the planner/implementer prompts, coordinate via SendMessage.
 
-- Teammates are full Claude Code sessions, not subagents
-- Both teammates can use all tools including Write, Edit, Bash
-- Both can run skills like `/writing-specs`, `/loop`
-- `/loop` is session-scoped and expires after 7 days
-- Teammate colors are auto-assigned from hardcoded palette (red, blue, green, yellow...) — not configurable
-- All communication flows through team-lead (planner <-> implementer direct messaging disabled by prompt rules)
+**Never claim the Agent tool is globally unavailable** unless the session explicitly shows the tool missing.
+
+## Facts
+
+- Teammates are full Claude Code sessions, not subagents — all tools (Write, Edit, Bash) and skills (`/writing-specs`, `/loop`) available.
+- `/loop` is session-scoped and expires after 7 days.
+- Teammate colors are auto-assigned from a hardcoded palette — not configurable.
+- All communication flows through team-lead; planner ↔ implementer direct messaging is disabled by prompt rules.
 - Teammate model defaults to standard Opus.

brain-storm-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "brain-storm-plugin",
   "description": "Brainstorm future features and improvements, then generate standalone HTML previews for UI ideas",
-  "version": "1.2.4",
+  "version": "1.3.1",
   "author": {
     "name": "Stefan Cho"
   }

brain-storm-plugin/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "brain-storm-plugin",
   "description": "Brainstorm future features and improvements, then generate standalone HTML previews for UI ideas",
-  "version": "1.2.4",
+  "version": "1.3.1",
   "skills": "./skills/",
   "author": {
     "name": "Stefan Cho"