claude-authoring: A Skill for Writing Claude Code Rules, Skills, and Plans

I write rules, skills, and plans for Claude Code constantly. Every time I learn something new about how to make Claude do the right thing, the lesson ends up in ~/.claude/rules/ or ~/.claude/skills/ so it sticks across sessions. The skill writing the skill is the meta-tool that keeps the rest of the toolkit honest.

The friction was always in the small details: rules use plain markdown without frontmatter, skills need YAML frontmatter with very specific fields, plans use status tracking. The trigger conditions for skills follow a specific pattern. The imperative form (“ALWAYS do X”) is required, not optional. The naming convention is kebab-case. If you forget any of these, the artifact silently degrades: a rule with frontmatter that does not auto-load, a skill with a trigger that never matches, a plan that loses its status.

claude-authoring is the skill I use to write all three correctly.

The problem the skill solves

Authoring a Claude Code rule looks like writing a markdown file. Authoring a skill looks like writing a different markdown file. They are not the same kind of markdown file:

Type	Purpose	Location	Format
Rule	Binding constraints (“NEVER do X”)	`rules/<name>.md`	Plain markdown, no frontmatter
Skill	Workflows + executable resources	`skills/<name>/SKILL.md`	YAML frontmatter + markdown
Plan	Implementation strategy for a task	`plans/<name>.md`	Markdown with status tracking

Get the format wrong and the artifact does not load. Get the trigger description wrong and the skill never fires. Get the imperative form wrong and the rule reads as a suggestion instead of a constraint.

The skill encodes the three formats as references and routes incoming requests to the right one.

What it does

Determines the task type from the request (“create a rule for X”, “write a skill that Y”, “draft a plan for Z”).
Reads the matching reference standard (one of three: rule-standard, skill-standard, plan-standard) before authoring.
Enforces shared writing conventions: imperative form, specific and testable directives, no second person, kebab-case naming.
For skills specifically: validates the YAML frontmatter (required fields, trigger description shape, invocation-only flag) before writing.
For rules: ensures plain markdown without frontmatter unless the rule is path-scoped.
For plans: includes status tracking sections (Now, Done, Next, Blocked).

How to invoke

The skill is user-invokable: false. It is intended to trigger automatically when Claude detects an authoring request, not via a slash command. Triggers include phrases like:

“create a rule for X”
“write a skill that does Y”
“draft a plan for Z”
“update the existing rule X”

Or by file path: any edit to ~/.claude/rules/<name>.md, ~/.claude/skills/<name>/SKILL.md, or ~/.claude/plans/<name>.md.

The skill does NOT trigger on “create a plan” alone, because Plan Mode in Claude Code handles that. The skill is for the persisted plan files, not the in-session plans.

A walkthrough

You realize that you want a rule that prevents Claude from auto-committing in any session. You type something like:

“Create a rule that says never auto-commit unless I say so.”

The skill activates:

Routing:
  Task: create a rule
  -> Read references/rule-standard.md

Rule standard summary:
  - Location: ~/.claude/rules/<name>.md
  - Format: plain markdown, no frontmatter (unless path-scoped)
  - Imperative form: ALWAYS or NEVER, not "you should"
  - Specific and testable: every directive must be verifiable
  - No second person: no "you", "your", "Claude"
  - kebab-case file name

Proposed file:
  Path: ~/.claude/rules/safety.md (existing file, will merge under "Commit safety")
  OR
  Path: ~/.claude/rules/commit-safety.md (new file)

  Existing rules in ~/.claude/rules/safety.md contain commit guidance already
  (NEVER run `git commit` unless the user explicitly says "commit"). Suggestion: merge.

Proceed with merge into safety.md?
> Yes

Reading safety.md... Editing under "Commit safety" heading...
  + Added line: "ALWAYS run `git status` and surface staged changes before any commit."
  + Added line: "NEVER amend an existing commit unless the user explicitly requests amend."

Edit applied.

Verification:
  - Imperative form: yes (ALWAYS, NEVER)
  - No second person: yes
  - Specific: yes (git status, surface staged changes)
  - Testable: yes (the directive is verifiable in review)

Now consider authoring a skill. You ask:

“Write a skill that creates a tmux session named after the current git branch.”

Routing:
  Task: create a skill
  -> Read references/skill-standard.md

Skill standard summary:
  - Location: ~/.claude/skills/<name>/SKILL.md
  - Required frontmatter: name, description
  - description must include trigger conditions in natural language
  - kebab-case folder and name
  - user-invokable: true (default) or false (opt-out)
  - disable-model-invocation: true if the skill should never auto-trigger
  - Imperative form in all directives
  - Workflow section: numbered steps

Proposed file:
  Path: ~/.claude/skills/tmux-from-branch/SKILL.md (new folder + file)

Generating...

  ---
  name: tmux-from-branch
  description: "Create or attach a tmux session named after the current git branch. Triggers on 'tmux session for this branch', 'start tmux for branch', 'tmux <branch>'. Usage: /tmux-from-branch"
  ---

  # tmux-from-branch

  Create or attach a tmux session named after the current git branch...

Verification:
  - Frontmatter: name + description present
  - Trigger phrases in description: yes
  - kebab-case: yes (tmux-from-branch)
  - user-invokable: implicit true (not set, default)
  - Workflow section: yes, numbered

Write file?
> Yes

Wrote ~/.claude/skills/tmux-from-branch/SKILL.md

The verification step is the part that catches the “missing trigger phrases” failure mode. A skill without trigger phrases in the description never fires automatically; the user has to type the slash command. That is fine if intentional, broken if not.

How it works under the hood

The skill itself has only a top-level router and three references:

references/rule-standard.md: the canonical pattern for rule files.
references/skill-standard.md: the canonical pattern for skill folders.
references/plan-standard.md: the canonical pattern for plan files.

The router reads the user request, classifies it as rule / skill / plan, and reads the matching reference before doing any authoring. This keeps the three standards isolated: changing the rule format does not affect skill authoring, and vice versa.

The shared conventions (imperative form, no second person, kebab-case) are listed in the main SKILL.md so they apply across all three artifact types. Each individual standard inherits these plus its own format-specific rules.

The “routing then read reference” pattern is worth stealing for any skill that handles multiple related-but-distinct tasks. The alternative (one big SKILL.md with branches) gets unwieldy as the formats diverge. Separating each format into its own reference keeps the main file small.

Gotchas

The skill is intentionally not user-invokable. user-invokable: false in the frontmatter means there is no /claude-authoring slash command. The skill triggers on detected authoring requests or file-edit context. This is to prevent the skill from being invoked when the user just wants to read a rule, not write one.
“Create plan” does NOT trigger this skill. Plan Mode in Claude Code handles in-session plans. This skill is for the persisted plans/*.md files that survive across sessions. The distinction matters: Plan Mode is a UI affordance, persisted plans are status-tracking documents.
Imperative form is required, not preferred. “Always”, “Never” instead of “you should”, “consider”, “try to”. This is the single most common authoring mistake. The skill flags any directive in second person or hedged form.
Trigger phrases in skill descriptions must be discoverable. The description should include the natural-language phrases that would cause the skill to fire. “Use when user says X, Y, Z.” If your skill is supposed to auto-fire on “deploy to staging”, that phrase must appear in the description.
Existing files get Edit-merged, not Write-overwritten. Same pattern as other skills in this toolkit: never blindly Write an existing file. The skill checks for existing rules with the same topic before adding a new one and offers to merge.

Writing rules and skills is the leverage point of the entire toolkit. Every rule you author saves you from one class of mistake in every future session. Every skill you author replaces a manual workflow with a deterministic one. But you only get that leverage if the authoring itself is correct: if the rule loads, if the skill triggers, if the plan persists with status.

The first rule I wrote loaded as ordinary text because I had added YAML frontmatter that did not match the schema. The first skill I wrote never auto-fired because I had no trigger phrases in the description. The first plan I wrote did not persist status because I had not included the tracking section. Each of those mistakes cost me an evening to debug.

For background on the three artifact types and how Claude Code loads them, claude-code-skills covers skills, claude-code-claude-md-rules covers the rules system, and claude-code-subagents covers subagent definitions (a fourth artifact type the skill could be extended to handle).

If you find yourself writing more than a couple of rules or skills per month, adopt this skill or write something similar. The reference-per-format split is the structural part; the shared conventions are the prose-level part. Both deserve a single source of truth.