Initial commit

skills/prompt-writing/references/artifact-guides/agents.md

@@ -0,0 +1,150 @@
+<agents>
+
+## Writing Claude Code Subagent Prompts
+
+Subagents are specialized AI assistants defined in markdown files with YAML frontmatter. Each subagent has its own context window and specific tool permissions. When generating subagent prompts, focus on effective frontmatter and purposeful system prompts.
+
+## Subagent File Structure
+
+**Format:**
+
+```
+---
+name: subagent-name
+description: Clear description of what this does and when to use it
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+System prompt content here.
+Define behavior, expertise, and workflow.
+```
+
+**File locations:** Project-level at .claude/agents/ or user-level at ~/.claude/agents/
+
+## Frontmatter Architecture
+
+**name (required):**
+Unique identifier. Use lowercase with hyphens.
+
+**description (required):**
+Critical field that determines when Claude invokes the subagent. Must include:
+
+1. What the subagent does
+2. When it should be used (include "USE PROACTIVELY" or "MUST BE USED" for automatic invocation)
+3. What context it needs to start
+4. How to trigger it (specific invocation phrases)
+
+Good: "Expert code reviewer. USE PROACTIVELY after code changes to check security, style, and maintainability. Reviews git diffs and provides prioritized feedback."
+
+Poor: "Reviews code" (too vague, no trigger conditions, no proactive signal)
+
+**tools (optional):**
+Comma-separated list. Omit to inherit all tools from main thread.
+Common: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch
+Principle: Grant only necessary tools.
+
+**model (optional):**
+Specify model or use "inherit" for main thread's model.
+
+## System Prompt Design
+
+The content after frontmatter defines the subagent's behavior. Use any prompting strategy that fits the purpose: Chain-of-Thought, Few-Shot, XML structure, decision frameworks, plain instructions.
+
+**System prompt should define:**
+
+- Role and expertise
+- Specific responsibilities and workflow
+- Constraints and boundaries
+- Expected output format
+- Edge case handling
+
+**No restrictions on approach:** The system prompt can be structured however best accomplishes the subagent's purpose.
+
+## Architecting Effective Descriptions
+
+The description determines when the subagent is invoked. Make it actionable and specific.
+
+**Trigger words:** "Use PROACTIVELY" or "MUST BE USED" encourage automatic invocation.
+
+**Specific conditions:**
+Good: "Use after code changes to run tests and fix failures"
+Bad: "Helps with testing"
+
+**Required context:**
+Good: "Analyzes git diffs to review changed code paths"
+Bad: "Reviews code"
+
+**Invocation clarity:**
+Description should make it obvious how to explicitly request this subagent using phrases like "use your [subagent-name] subagent to..." or "use the [subagent-name] subagent for..."
+
+## System Prompt Patterns
+
+**Goal-Oriented:**
+Define what to accomplish, let subagent determine approach within constraints.
+
+**Process-Driven:**
+For workflows requiring specific steps (TDD, security audits), outline them explicitly.
+
+**Tool-Aware:**
+Reference available tools and when to use them.
+
+**Output-Focused:**
+Specify expected format (JSON, markdown, structured reports).
+
+**Any Strategy Works:**
+CoT for complex reasoning, Few-Shot for specific patterns, XML for organization, decision trees for branching logic.
+
+## Common Subagent Architectures
+
+**Read-Only Analyst:**
+tools: Read, Grep, Glob
+Purpose: Analyze and provide feedback without modification
+
+**Code Implementer:**
+tools: Read, Write, Edit, Bash, Grep, Glob
+Purpose: Implement features, fix bugs, modify code
+
+**Test Executor:**
+tools: Read, Bash, Grep
+Purpose: Run tests, analyze failures, report results
+
+**Documentation Writer:**
+tools: Read, Write, Grep, Glob
+Purpose: Generate or update documentation
+
+**Research Specialist:**
+tools: Read, Grep, WebSearch, WebFetch
+Purpose: Gather information, analyze patterns
+
+## What to Include When Generating Subagent Prompts
+
+**Frontmatter design:**
+
+- Clear, unique name
+- Actionable description with trigger conditions and context needs
+- Minimal necessary tool permissions
+- Model choice if needed
+
+**System prompt design:**
+
+- Clear role definition
+- Specific responsibilities
+- Workflow or approach guidance
+- Constraints and boundaries
+- Output expectations
+- Appropriate prompting strategy for the task
+
+## What to Avoid
+
+**Vague descriptions:** Claude won't know when to invoke the subagent
+
+**Over-permissioning:** Only grant necessary tools for security and focus
+
+**Rigid process when flexibility needed:** Allow adaptation within constraints
+
+**No trigger guidance:** Without clear conditions, subagent may never be automatically invoked
+
+**Missing context requirements:** Specify what the subagent needs to start effectively
+
+</agents>

skills/prompt-writing/references/artifact-guides/commands.md

@@ -0,0 +1,152 @@
+<commands>
+
+## Command Namespacing
+
+Organize commands in subdirectories. Subdirectory names appear as labels but don't change invocation.
+
+- `commands/command.md` → `/command`
+- `commands/namespace/command.md` → `/command` (labeled with namespace)
+
+## Command File Structure
+
+Command files can contain optional frontmatter followed by the prompt content.
+
+**Frontmatter (Optional but Recommended):**
+
+```yaml
+---
+description: Brief description of what this command does
+argument-hint: [issue-number] [priority]
+allowed-tools: "Bash(git:*), Read, Write"
+model: claude-3-5-haiku-20241022
+disable-model-invocation: false
+---
+```
+
+All frontmatter fields are optional:
+- `description`: Brief description (defaults to first line of prompt). Include this for SlashCommand tool discovery.
+- `argument-hint`: Expected arguments for auto-completion
+- `allowed-tools`: Tools this command can use (inherits from conversation if omitted)
+- `model`: Specific model to use (inherits from conversation if omitted)
+- `disable-model-invocation`: Set to true to prevent SlashCommand tool from calling this command (defaults to false)
+
+**Prompt Content:**
+
+After frontmatter (or if no frontmatter), the markdown content becomes the prompt Claude receives.
+
+Simple example:
+```
+Run the test suite and report any failures in the scratchpad.
+```
+
+Example with frontmatter:
+```yaml
+---
+description: Fix GitHub issues following TDD workflow
+argument-hint: [issue-number]
+allowed-tools: "Bash(gh:*), Read, Write, Edit"
+---
+
+Analyze GitHub issue $ARGUMENTS and create a fix:
+1. Use `gh issue view $ARGUMENTS` to read the issue
+2. Identify the root cause
+3. Implement a fix
+4. Run tests to verify
+```
+
+## Argument Handling
+
+Commands support two argument patterns:
+
+**`$ARGUMENTS` - All arguments as single string:**
+
+Captures everything after the command name as one value.
+
+Example:
+
+- Command file contains: `Fix issue $ARGUMENTS`
+- Invocation: `/fix-issue 123 high-priority`
+- Result: `$ARGUMENTS` becomes `123 high-priority`
+- Claude receives: `Fix issue 123 high-priority`
+
+**Positional Parameters (`$1`, `$2`, `$3`) - Individual arguments:**
+
+Access specific arguments separately, like shell script parameters.
+
+Example:
+
+- Command file contains: `Review PR #$1 with priority $2 assigned to $3`
+- Invocation: `/review-pr 456 high alice`
+- Result: `$1` = `456`, `$2` = `high`, `$3` = `alice`
+- Claude receives: `Review PR #456 with priority high assigned to alice`
+
+**When to use each:**
+
+- `$ARGUMENTS`: All input as single value (commit messages, search queries, issue numbers with descriptions)
+- `$1, $2, $3`: Multiple distinct values (PR number + priority + assignee, file path + operation + output format)
+
+## Special Command Features
+
+**Bash Execution (`!` prefix):**
+
+Execute bash commands before the slash command runs. The output is included in the command context.
+
+Example:
+
+```yaml
+---
+description: Analyze current git status and suggest next steps
+allowed-tools: "Bash(git:*)"
+---
+
+Current git status:
+!`git status --short`
+
+Based on the above status, suggest what to do next.
+```
+
+Note: Requires `allowed-tools` frontmatter with Bash tool specified.
+
+**File References (`@` prefix):**
+
+Include file contents directly in the command context.
+
+Example:
+
+```markdown
+Review the implementation in @src/auth/login.js and suggest improvements.
+```
+
+**Extended Thinking:**
+
+Activate extended thinking by including relevant keywords in command definitions.
+
+Example:
+
+```markdown
+Think deeply about the architecture implications of this change and analyze thoroughly before proposing a solution.
+```
+
+## Commands vs Other Formats
+
+**Command vs Skill:** Command is a prompt stored in `.claude/commands/`, invoked explicitly with `/`. Skill is instructions in a folder, invoked automatically when Claude determines it's relevant.
+
+**Command vs CLAUDE.md:** Command is a prompt you explicitly invoke when needed. CLAUDE.md is context automatically loaded at the start of every conversation.
+
+**Command vs Just Typing:** Command saves typing for repeated prompts, shareable via git. Typing is appropriate for one-off requests or things you don't repeat.
+
+## What Matters When Generating Command Prompts
+
+When your prompt-writing skill generates a prompt for a command, it should:
+
+**Understand the use case:** Is this a repeated workflow? Does it need parameters?
+
+**Be complete:** The prompt should contain all instructions needed. Commands don't have special powers - they're just text that becomes Claude's input.
+
+**Use $ARGUMENTS appropriately:** If the workflow needs input, use `$ARGUMENTS`. If it doesn't, don't include it.
+
+**Be explicit:** Commands execute exactly as written. Don't assume Claude will infer missing steps.
+
+**Consider prompting techniques:** Commands can use any prompting strategy (CoT, Few-Shot, XML, etc.) - they're just prompts in files.
+
+</commands>

skills/prompt-writing/references/artifact-guides/reference_documents.md

@@ -0,0 +1,87 @@
+<documents>
+
+## Writing Reference Documents for Claude Code
+
+Reference documents provide context that helps Claude Code understand projects. When generating prompts that create or improve reference documents, focus on making them useful without bloating context windows.
+
+## File Reference Strategies
+
+**In reference documents:**
+
+Use plain paths (the default):
+
+- In reference documents pointing to other docs
+- Troubleshooting guides that are conditionally relevant
+- Architecture documentation that applies to specific scenarios
+- Any "available if needed" reference
+- When you want Claude to decide based on the actual task
+
+Avoid @ in reference docs - it force-loads content unnecessarily.
+
+## Providing Context with Plain Paths
+
+When using plain paths in reference documents, explain when the file is relevant so Claude knows when to read it.
+
+**Good examples:**
+"For database migration failures, see docs/db-troubleshooting.md"
+"Authentication implementation details are in docs/auth-architecture.md"
+"If encountering FooBarError, consult docs/foobar-guide.md"
+
+**Poor examples:**
+"See docs/troubleshooting.md" (no context about when)
+"@docs/troubleshooting.md" (forces load unnecessarily)
+"docs/file1.md, docs/file2.md, docs/file3.md" (just a list with no guidance)
+
+## Progressive Disclosure
+
+For complex reference docs, use progressive disclosure: overview first, details in XML-tagged sections.
+
+Example: Overview paragraph explaining the system, then `<authentication_details>`, `<payment_processing>`, `<error_handling>` sections with specifics.
+
+## What Makes Effective Reference Documents
+
+**High-Value Content:**
+
+- Project structure (where things live)
+- Conventions and patterns actually used
+- Architecture decisions with rationale
+- Domain-specific business concepts
+- Non-obvious behaviors
+- Where to find key functionality
+- Pointers to detailed docs (plain paths with context)
+
+**Low-Value Content:**
+
+- Obvious information about languages or frameworks
+- Rapidly changing information
+- Exhaustive details better kept elsewhere
+- Information obvious from code
+- Force-loaded content (via @) that's rarely needed
+
+## Composition Guidance
+
+**Default to Plain Paths:** Reference files without @. Provide context about when they're relevant. Let Claude decide when to read them.
+
+**Be Specific:** Concrete facts beat vague descriptions. "JWT tokens expire after 1 hour" beats "modern auth patterns".
+
+**Explain Relevance:** "For database migration errors, see docs/db-troubleshooting.md" tells Claude when that file matters.
+
+**Stay Concise:** Every word should add value. Verbosity wastes context budget.
+
+**Trust Claude's Judgment:** Plain paths let Claude determine what's relevant based on the actual task. This is usually better than forcing content into context upfront.
+
+## Writing Prompts for Reference Documents
+
+When generating a prompt that asks Claude Code to create or improve a reference document, include guidance on:
+
+**Structure:** Overview first, details organized logically, progressive disclosure for complex topics
+
+**Content Selection:** Focus on non-obvious information, explain the "why" not just "what"
+
+**References:** Plain paths with context about when files are relevant
+
+**Brevity:** Make every sentence count, remove redundancy, assume Claude knows common concepts
+
+**Maintenance:** Write content that stays relevant, avoid time-sensitive details, make it easy to update
+
+</documents>

skills/prompt-writing/references/artifact-guides/skills.md

@@ -0,0 +1,24 @@
+<skills>
+
+## SKILL.md Format
+
+**Frontmatter (REQUIRED):**
+Two fields are mandatory:
+
+- name: Unique identifier (lowercase, hyphens for spaces)
+- description: Complete description following this pattern:
+  1. What the skill does
+  2. When to use it (be specific about context)
+  3. What it needs (when applicable)
+  4. How to trigger it (specific phrases: "Trigger with phrases like '[action] [context]'")
+
+Example: "Generates, analyzes, and optimizes prompts for skills, commands, subagents, reference docs, and free-form text. Use when generating prompt content, analyzing prompt files, or optimizing prompt text. Trigger with phrases like '[generate|analyze|optimize] prompt', '[generate|analyze|optimize] [file-path]', 'create [skill|command|subagent]'."
+
+**Optional Frontmatter:**
+
+- allowed-tools: Scope tool access (e.g., `allowed-tools: "Read, Bash(git:*)"`)
+
+**Markdown Body (FLEXIBLE):**
+No required structure. Use any prompting strategy.
+
+</skills>