# Skill Management

**Purpose:** Standards for managing skills and commands. Important context (as of Claude Code's 2026 merge): **custom commands have been merged into skills.** A file at `.claude/commands/foo.md` and a skill at `.claude/skills/foo/SKILL.md` both produce `/foo` and work the same way. The historical distinction between "commands" and "skills" is now mostly cosmetic.

---

## One Surface, Two Shapes

Both commands and skills resolve as slash commands:

| Shape | Path | When to use |
|---|---|---|
| **Command file** | `{scope}/commands/{name}.md` or `{scope}/commands/{name:sub}.md` | Short, single-file definitions. Namespaced with colons (e.g. `1000xagent:inspect`). My dashboards, system operations, and simple commands use this shape. |
| **Skill directory** | `{scope}/skills/{name}/SKILL.md` | When the slash command needs supporting files (templates, scripts, research notes alongside the SKILL.md) or when the name has colons that conflict with filesystem naming. |

Pick whichever produces the cleaner file on disk. If it's a single-file workflow, command file. If it has supporting material or the name uses colons for namespacing, skill directory.

---

## Invocation Control

The behaviors that used to distinguish commands from skills are now frontmatter knobs:

| Frontmatter | Effect |
|---|---|
| *(default)* | User can invoke via `/`; Claude can also auto-invoke based on description match |
| `disable-model-invocation: true` | Only user can invoke; Claude will never trigger it automatically |
| `user-invocable: false` | Hidden from the `/` menu; only Claude can invoke |

Set `disable-model-invocation: true` for anything with side effects Tyler doesn't want fired accidentally (deploys, pushes, destructive ops). Set `user-invocable: false` for skills Claude uses internally (session-state hooks, domain-context loaders).

### `disable-model-invocation: true` — what it actually blocks

This frontmatter has tripped up multiple agents (463 homework skill 2026-03-23, 468 project-verify 2026-04-12). The precise semantics:

| Invocation path | `disable-model-invocation: true` | `disable-model-invocation: false` / absent |
|---|---|---|
| User types `/skill-name` in prompt | ✅ Works | ✅ Works |
| Claude calls the Skill tool | ❌ Blocked — tool returns error | ✅ Works |
| Claude auto-invokes based on description | ❌ Never happens | ✅ Happens when description matches context |

**The trap:** if you set `true` on a skill and then try to call it via the Skill tool in the same session, the tool fails with an error that isn't always obvious. The skill exists, the frontmatter is valid, but the Skill tool path is closed. Only a literal `/skill-name` from the user will activate it.

**When to use `true`:** side-effect skills Tyler should always initiate consciously (deploys, destructive file ops, external API writes, auto-commit flows).

**When to use `false` / leave absent:** workflow skills Claude should be able to orchestrate mid-task (verification runs, context loaders, research agents, homework workflows that chain together).

**Check the frontmatter before invoking via Skill tool.** If I'm about to call `Skill({skill: "foo", ...})` and `foo`'s frontmatter has `disable-model-invocation: true`, the call will fail — either edit the frontmatter first (if appropriate) or tell Tyler to invoke it manually.

---

## Valid Frontmatter Fields

### For skill SKILL.md files

| Field | Notes |
|---|---|
| `description` | Used for auto-invocation matching. Recommended. |
| `name` | Override display name (defaults to directory name) |
| `argument-hint` | Autocomplete hint (e.g. `<week-number>`) |
| `disable-model-invocation` | `true` = user-only |
| `user-invocable` | `false` = Claude-only |
| `allowed-tools` | Tools callable without permission prompt |
| `model` | Model override |
| `context` | Set to `fork` for subagent context |
| `agent` | Subagent type when `context: fork` |
| `hooks` | Skill-scoped hooks |

### For command files

Same list, plus: `description`, `allowed-tools`, `model`, `argument-hint` are the historically-supported ones. The skill fields also work in command files post-merge.

**Invalid:** `match_prompt` and any field not listed above — Claude Code ignores unknown fields.

---

## Naming

- Skill directories on disk: lowercase-with-hyphens, no colons (`1000xagent-audit-identity/`).
- Skill frontmatter `name:` field: may use colons for namespacing (`name: 1000xagent:audit:identity`). The frontmatter name is what resolves as the slash command.
- Command files on disk: lowercase, colons allowed (`1000xagent:audit:identity.md`).
- Prefix with agent namespace (`1000xagent:*`) for things I own; leave cross-cutting utilities un-prefixed (`/spec`, `/solve`, etc.).

### Sub-namespaces for my own commands (convention from TODO #677 onward)

For any new `1000xagent:*` command or skill, use a sub-namespace that reflects its domain:

- `1000xagent:orchestrate:*` — cross-repo operations (push-all, propagate)
- `1000xagent:audit:*` — inspection/audit (inspect, audit-identity, audit-redundancy, validate-folder, audit-permissions, analyze-logs)
- `1000xagent:enhance:*` — enhancement flows (enhance-agent, maintain-claude-folder, workflow-enhance, optimize-repo)
- `1000xagent:init:*` — scaffolding (create-project, fork-init)

Existing flat-namespace commands (e.g. `1000xagent:inspect`, `1000xagent:enhance-agent`) are not renamed — they work as aliases until a dedicated migration TODO retires them. New commands created from 2026-04-17 onward use the sub-namespace.

---

## Context Budget

Skill descriptions share a ~15,000-character context budget (configurable via `SLASH_COMMAND_TOOL_CHAR_BUDGET`). Skills with `disable-model-invocation: true` do NOT consume it. Keep descriptions tight — 1–2 sentences is the target.

---

## Where Things Live

- **My own (`1000xagent:*`) commands + cross-cutting utilities** → `~/.claude/commands/` or `~/.claude/skills/`. The global folder is mine exclusively.
- **Project-agent activation commands + project-scoped skills** → `{repo}/.claude/commands/` or `{repo}/.claude/skills/`. Never in my global folder.

See `project-level-agents.md` (the 5-piece contract) and `agent-authority.md` (my folder is mine).

---

## Anti-Patterns

- ❌ Creating a command in `~/.claude/commands/` named after a project agent (that's a leak; project-agent commands live in their repos)
- ❌ Making every workflow a skill when a command file would do (inflates context budget unnecessarily)
- ❌ Duplicating content between a command and a skill with the same name (pick one shape; delete the other)
- ❌ Using `match_prompt` or `triggers:` or other invalid fields (Claude Code ignores them silently; you think it's wired up and it's not)

---

## Context-First Authoring Standard

**Every new skill that touches more than 1 file MUST have a Phase 1 context-load with status table and pre-write gate.** This is the discipline codified in `~/.claude/rules/slash-command-tool-sequencing.md`; this section is the index entry that points to it.

The minimum shape:

```markdown
## Phase 1: Load Context (MANDATORY)

### Step 1: Enumerate source files
<bash find/glob block>

### Step 2: Read all enumerated files
<Read calls — parallel batch in single message if >3 files>

### Step 3: Emit status table
| File | Read | Summary |
|---|---|---|

### Pre-write gate
- [ ] Have I read all source files?
- [ ] Have I checked prior submissions for this task?
- [ ] Have I loaded the rubric / spec / standard?
yes/yes/yes required before any subsequent phase.
```

**Forbidden:** AskUserQuestion as Step 1. The question must be informed by loaded context, not used to fish for context. See `~/.claude/rules/askuserquestion-empty-answer.md` for the defensive parsing layer on top of this.

**Exceptions** (skills that legitimately skip Phase 1):

- Pure dashboards — read-and-render only, no decisions to make
- Pure preprocessing skills — single-file transformations with no state to load

---

## Subagent-Dispatch Decision Matrix

When a skill needs to read multiple files, the dispatch shape depends on count + variety:

| File count | Distinct file types | Approach |
|---|---|---|
| 1–3 | any | Direct Read tool calls, sequential is fine |
| 4–15 | ≤3 | Parallel Read batch in a single message |
| 4–15 | >3 | Parallel Read batch; consider Agent subagent if types need distinct processing |
| >15 | any | Dispatch parallel subagents via Agent tool. Set `context: fork` in frontmatter if applicable. |
| >50 | any | Multi-axis subagent fan-out (the `/spec` 4-axis pattern). All subagents in a single message. |

**The parallel-call hint** — skills that benefit from parallelism must say so explicitly: "Launch these N reads in a single message so they execute in parallel" or "Dispatch the following N subagents in parallel via the Agent tool, each in a separate tool-use block within the same message."

Without the hint, Claude defaults to sequential reads.

---

## Frontmatter Completeness Gate

Every skill / command MUST have:

- [ ] **`description:`** — present, under 200 chars, includes both what AND when
- [ ] **`allowed-tools:`** — SHOULD be present (defense-in-depth Layer 5 over bypass-permissions)
- [ ] **`disable-model-invocation: true`** — if any side-effect category applies (see table below)
- [ ] **`argument-hint:`** — if the skill takes arguments

Invalid fields silently no-op. Verify field names against the table in §"Valid Frontmatter Fields" above.

### Side-Effect Categories (require `disable-model-invocation: true`)

| Category | Examples |
|---|---|
| File writes outside CWD | Cross-repo edits, registry mutations, log appends to non-CWD paths |
| Git mutations | Commits, pushes, branch creation, tag creation |
| Network mutations | Vercel deploys, GitHub API writes, Porkbun DNS edits, Cloudflare API |
| Filesystem destructive | `rm`, `mv` over existing files, dir restructuring |
| External API writes | Resend email send, Slack post, Discord webhook, any third-party POST |
| Auth-bearing operations | Any tool call using a private credential |

Read-only skills (audits, validators, dashboards, status reports) should NOT have `disable-model-invocation: true` — that blocks Claude from auto-invoking them when the description matches, defeating the point.

---

## See Also

- `~/.claude/rules/slash-command-tool-sequencing.md` — tool sequencing, parallel-call discipline, Phase 1 shape
- `~/.claude/rules/claude-folder-spec.md` — canonical folder structure + valid field reference
- `~/.claude/rules/askuserquestion-empty-answer.md` — empty-payload defensive parsing
- `~/.claude/rules/single-option-default.md` — response-shape contract (no menu-asking)
- `~/.claude/skills/SKILL-TEMPLATE.md` — 2026-style scaffold incorporating all of the above