New Skill

---
name: new-skill
description: Author a new, well-formed Claude Code skill, agent, or hook from a one-line intent. Decides the right artifact type (skill vs agent vs hook) and placement (global vs project), then writes a correct SKILL.md / agent file / settings.json hook with engineered trigger phrasing, a clear procedure, and guardrails. Global and project-agnostic. Trigger when the user says "new skill", "new-skill", "create a skill", "make an agent", "scaffold a skill/agent/hook", or "author a Claude command".
---

# Author a new skill / agent / hook

Project-agnostic, global skill. It turns a one-line intent into a correct, well-formed
Claude Code extension - choosing the right artifact type and placement, then writing the
file in the house style used across these skills. It is the *correct-builder* downstream
of `propose-automation` (which decides *what* to build); this one builds one well.

## The judgment this skill exists to encode
Two mistakes are easy to make by hand; this skill must get them right:
1. **Artifact type.**
   - **Skill** = a repeatable procedure the user invokes (`/name`); runs in the main
     thread with project context.
   - **Agent** = isolatable / parallel / noisy work (large reads, fan-out, web search),
     with a restricted toolset. Often spawned *inside* a skill, not as the top-level UI.
     Define a custom agent only when you need a named, reusable role.
   - **Hook** = deterministic automation that must *always* run on an event
     (PreToolUse/PostToolUse/Stop/etc.), wired in `settings.json`. Any "from now on
     when X / every time X / before-after X" request is a HOOK, not a skill - the harness
     runs it, not Claude. Route those to the `update-config` skill.
2. **Trigger quality.** A skill only auto-fires when its `description` names concrete
   trigger phrases and conditions. A vague description = a skill that never runs. Engineer
   the `description` for retrieval: state what it does AND when to use it, with example
   trigger phrases, and (where useful) when NOT to use it.

## Placement
- **Global** (`~/.claude/skills/<name>/SKILL.md`, `~/.claude/agents/<name>.md`) only when
  genuinely project-agnostic.
- **Project** (`./.claude/...`) when coupled to this repo's conventions/paths; it then
  travels and is versioned with the repo. This is the default when there is any coupling.
- Ask when ambiguous. In a submodule/monorepo, confirm which package owns it.

## Procedure

### 1. Capture intent
- Use the user's one-line description. If missing or vague, ask up to ~3 questions: what
  it does, when it should trigger, and global vs project.

### 2. Classify the artifact (and say why)
- Decide skill / agent / hook per the judgment above; state the reason in one line.
- If it is really a hook, do not write a SKILL.md - hand off to `update-config` and stop.
- If it needs noisy fan-out/web work, propose an accompanying agent the skill will call.

### 3. Pick name + placement
- Kebab-case `name`; check it does not collide with an existing skill/agent (scan
  `~/.claude/skills`, `~/.claude/agents`, and `./.claude/...`). Choose global vs project
  and the exact target path; confirm if ambiguous.

### 4. Write the file
For a **skill** (`SKILL.md`): YAML frontmatter with `name` and a retrieval-engineered
`description` (what + when + trigger phrases + optional skip conditions), then a title,
a short purpose line, a numbered **Procedure**, and a **Guardrails** section. Add a
"Deferred / not worth it" pattern only where it fits. Match the concise house style of
the existing skills.
For an **agent** (`.claude/agents/<name>.md`), follow the agent-authoring guidance below.

### 5. Validate
- Confirm the YAML/JSON parses, the name is unique, and the path/folder is correct.
- Sanity-check that the `description` would actually trigger on the intended phrases.

### 6. Hand off
- Report what was created and where. Remind the user that skills/agents are indexed at
  session start, so a restart is needed before the new `/command` autocompletes.

## Authoring an agent (the agent branch of step 4)

### When an agent is actually warranted
Prefer a skill, or letting a skill spawn a *built-in* agent, over defining a custom one.
Define a custom agent (`.claude/agents/<name>.md`) only when you need a **named, reusable
role** with a **restricted toolset**, typically because the work is:
- **Isolatable / context-noisy** - large reads, repo-wide fan-out, or web research whose
  intermediate output would pollute the main thread; the agent returns only a conclusion.
- **Parallelizable** - several independent investigations run at once.
- **Role-stable** - the same constrained job recurs across tasks, so a named role beats
  re-describing it each time.
If the need is one-off or generic, do NOT create a custom agent - have the skill spawn the
built-in `Explore` (read-only fan-out search) or `general-purpose` agent instead, and say so.

### Choose a minimal toolset (least privilege)
Grant the smallest `tools` set the role needs; every extra tool is surface area and noise.
- **Read-only research / search role:** `Read, Grep, Glob` (+ `WebSearch, WebFetch` if it
  needs the internet). No `Edit`/`Write`/`Bash` - it reports, it does not mutate.
- **Code-writing role:** add `Edit, Write` and a *scoped* `Bash` only if it must run
  commands; never grant broad shell access "just in case".
- Omit the `tools` field only when the role genuinely needs the full default set; prefer an
  explicit allowlist so the role's boundaries are legible.
- Mirror the restraint of `/setup-permissions`: never hand an agent destructive Bash
  (`rm`, `sudo`, force-push) unless that is its explicit, reviewed purpose.

### Write a role-shaped definition
- **Frontmatter:** `name` (kebab-case), a retrieval-engineered `description` that states
  what the agent is for AND when to delegate to it (so the parent model picks it), an
  explicit `tools` list, and an optional `model` override only if the role needs it.
- **Body:** write the agent's *operating instructions as a role*, not a procedure for the
  user - it runs autonomously and cannot ask follow-ups mid-run. Cover: its objective and
  scope, what it must NOT do, how to handle ambiguity without a human, and the exact shape
  of the **final message** it returns (the parent only sees that final output, so specify
  it - e.g. "return a ranked list with one-line rationales, no file dumps").

### Pair it with its caller
An agent is usually a *step inside a skill*, not a user-facing command. When you create one,
say which skill should spawn it and how, and note that users do not invoke agents with a
slash command the way they invoke skills.

## Guardrails
- Always classify artifact type first; never write a SKILL.md for what is really a hook
  (route hooks to `update-config`).
- Engineer the `description` for triggering; a skill with weak triggers is a bug.
- For agents: grant a minimal least-privilege `tools` list and specify the final-message
  shape; prefer a built-in agent over a new custom one when the need is one-off or generic.
- Default to project placement when there is any repo coupling; global only when agnostic.
- Check for name collisions before writing; never clobber an existing skill/agent.
- Write thin, single-purpose artifacts that reference sources of truth rather than
  duplicating them; keep guardrails explicit.
- Never fabricate facts about the repo or the harness.