New skill

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.