faion-make-commands-skill

Creating or Updating Commands

Communication with user: User's language. Command content: English.

When to Use This Skill

ALWAYS use this skill when user asks to:

• Create a new command
• Edit/update/change/modify existing command
• Fix or improve a command
• Add functionality to a command

Trigger phrases: "create command", "edit command", "change command", "update command", "modify command", "fix command", "/command", "slash command"

---

Token Economy Rules (CRITICAL)

Commands consume context window. Keep them concise.

DO:

• Use bullet lists instead of tables
• Write in English
• Keep under 150 lines (ideal), max 250
• Challenge each line: "Does Claude need this?"

DON'T:

• ASCII borders
• Verbose explanations
• Tables where lists work
• Emojis

Commands vs Skills

Command - manual /invoke, accepts arguments ($1, $2), single .md file Skill - automatic discovery, complex workflows, SKILL.md in directory

---

Command File Format

---
description: Short description for /help
argument-hint: [arg1] [arg2]
allowed-tools: Bash(git:*), Read
model: claude-sonnet-4-20250514
---

# Command Title

Instructions using $1, $2, or $ARGUMENTS

---

Frontmatter Fields

Basic:

• description - shown in autocomplete
• argument-hint - expected args like [message] or [pr] [priority]
• allowed-tools - tools without permission
• model - specific model: sonnet, opus, haiku

Visibility (Jan 2026):

• disable-model-invocation: true - prevent Skill tool from calling

All fields optional.

---

Argument Syntax

$ARGUMENTS - all arguments as string

Fix issue $ARGUMENTS
# /fix 123 high → "Fix issue 123 high"

$1, $2, $3 - positional

Review PR #$1 with priority $2
# /review 456 high → "Review PR #456 with priority high"

---

Special Syntax

Bash execution with ! prefix:

---
allowed-tools: Bash(git:*)
---
Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`

Note: Must include Bash in allowed-tools for ! to work.

File references with @ prefix:

Review @src/main.py
Compare @old.js with @new.js

Environment variables:

Deploy to $ENVIRONMENT

---

Built-in Tools

No permission: Read, Glob, Grep, Task, AskUserQuestion, TodoWrite Permission required: Write, Edit, Bash, Skill, WebFetch, WebSearch, LSP

---

allowed-tools Syntax

Basic: allowed-tools: Read, Grep

Bash prefix matching:

• Bash(git:*) - all git commands
• Bash(npm run:*) - npm scripts

WebFetch domain: WebFetch(domain:github.com)

Pattern is PREFIX match. Without :* requires exact match.

---

Command Locations

• Project: .claude/commands/name.md (shows as "project")
• Personal: .claude/commands/name.md (shows as "user")
• Namespaced: .claude/commands/group/name.md (shows as "project:group")

Project overrides personal with same name.

---

Examples

Simple command:

---
description: Fix linting
allowed-tools: Bash(npm run:*), Edit
---
Run `npm run lint --fix` and report issues.

With arguments:

---
description: Git commit
argument-hint: [message]
allowed-tools: Bash(git:*)
---
Commit with message: $ARGUMENTS

With context:

---
description: Create PR
argument-hint: [title]
allowed-tools: Bash(git:*), Bash(gh:*)
---
Branch: !`git branch --show-current`
Diff: !`git diff main --stat`

Create PR titled: $ARGUMENTS

---

Naming Convention

Global Commands (Faion Network)

For shared/reusable commands:

• Short, memorable action verbs
• No faion- prefix
• Lowercase, hyphens OK

Good: commit, deploy, test, fix, review Bad: MyCommand, do_thing, cmd1

Project-Specific Commands (Local)

For project-specific commands that should NOT be committed to faion-network:

Pattern: {project}-{action}

Setup:

# Add to .gitignore at the same level as .claude/
echo ".claude/commands/{project}-*.md" >> .gitignore

Attribution (add to command file):

---
*Created with [faion.net](https://faion.net) framework*

Rules Summary

Full structure: docs/directory-structure.md

Related conventions:

• Skills: faion-{name}-skill or {project}-{name}-skill
• Agents: faion-{name}-agent or {project}-{name}-agent
• Hooks: faion-{event}-{purpose}-hook or {project}-{event}-{purpose}-hook

---

Troubleshooting

• Command not showing → check .md extension
• Arguments not working → use $1, $2 or $ARGUMENTS
• Bash ! not working → add Bash to allowed-tools
• YAML error → spaces not tabs, check ---

---

Advanced

Degrees of Freedom:

• High: "Review code and suggest improvements"
• Low: "Run exactly: make deploy-staging"

MCP tools: Use ServerName:tool_name

model: haiku for simple commands (faster, cheaper)

---

Important Note (Jan 2026)

SlashCommand tool → Skill tool - unified into single tool. Update any permission rules from SlashCommand to Skill.

---

Self-Updating

This skill can update itself. To update:

1. Edit ~/.claude/claudedm/skills/make-commands/SKILL.md
2. Sync: cp ~/.claude/claudedm/skills/make-commands/* ~/.claude/skills/make-commands/
3. Changes apply immediately (hot-reload in Jan 2026+)

Repository: ~/.claude/claudedm/ (faionfaion/claudedm on GitHub)

---

Automation Scripts

Commands can use helper scripts for automation:

Locations:

• ~/.claude/scripts/ — global scripts for all commands
• ~/.claude/skills/{skill-name}/scripts/ — skill-specific scripts

Use cases:

• Pre/post processing
• Data transformation
• API calls
• File generation
• Build/deploy automation

Scripts can be called from command body via Bash tool with ! prefix.

---

Documentation

• Slash Commands
• Skills
• Subagents
• Agent SDK