claude-artifact-creator

Before creating any artifact, READ .claude/GUIDELINES.md for:

• Decision framework (Skill vs Agent vs Command vs Hook)
• Tool permissions strategy by role
• Hook events and configuration
• Agent/Skill/Command file formats
• Quality checklists and anti-patterns

This skill provides quick patterns; GUIDELINES.md provides authoritative rules.

• Creating a new skill for domain expertise or file processing
• Creating an agent for specialized tasks with context isolation
• Creating a command for user-invoked shortcuts
• Improving or refactoring existing artifacts
• Reviewing artifacts against quality standards
• Analyzing staged changes for automation opportunities
• Consolidating duplicate or overlapping artifacts

The context window is a shared resource. Before adding content, ask:

• "Does Claude really need this?" - Claude is already smart
• "Can this be in a reference file?" - Progressive disclosure
• "Does this justify its token cost?" - Every line has a cost

1. Create - Generate artifacts from templates with proper structure
2. Improve - Enhance based on official best practices and patterns
3. Review - Audit against quality checklist and anti-patterns
4. Consolidate - Merge duplicate artifacts into focused ones

---

CRITICAL: Before creating any knowledge artifact, determine the correct layer.

See [GUIDELINES.md § Three-Layer Knowledge Architecture](../../GUIDELINES.md#three-layer-knowledge-architecture) for full details.

Quick Decision Flow

```

Is it a design principle that applies to ANY language?

│

├── YES → Create CONCEPT (knowledge/concepts/)

│ NO CODE, just principles

│

└── NO → Is it specific to a language/framework?

│

├── YES → Create IMPLEMENTATION (knowledge/implementations/{lang}/)

│ CODE EXAMPLES, links to concept

│

└── NO → Create SKILL (skills/)

ORCHESTRATION, references both

```

Creating Concepts

Location: knowledge/concepts/{topic}/{concept}.md

Rules:

• ✅ Framework-independent principles only
• ✅ Why it matters (rationale)
• ✅ How to detect violations (criteria, not code)
• ❌ NO code examples
• ❌ NO language-specific syntax

Template:

```yaml

---

name: {Concept Name}

category: {topic}

implementations:

dotnet: ../implementations/dotnet/{file}.md#{anchor}

react: ../implementations/react/{file}.md#{anchor}

used_by_skills: []

---

# {Concept Name}

> "{Quote or one-liner definition}"

{Framework-independent explanation}

{Business/technical rationale}

• {Detection criteria - NO code}
• {Observable symptoms}

• [{Related Concept}](../{related}/concept.md)

| Language | Guide |

|----------|-------|

| C#/.NET | [Link](../../implementations/dotnet/{file}.md) |

| React | [Link](../../implementations/react/{file}.md) |

```

Creating Implementations

Location: knowledge/implementations/{lang}/{file}.md

Rules:

• ✅ Links to concept(s) it implements
• ✅ ❌ Bad / ✅ Good code examples
• ✅ Framework-specific notes
• ❌ NO principle definitions (link instead)
• ❌ NO "why" explanations (concept layer)

Template:

```yaml

---

implements_concepts:

- concepts/{topic}/{concept}

language: {csharp|typescript|python}

framework: [{dotnet|react|abp}]

---

# {Concept Name} in {Language}

> Concept: [{Concept Name}](../../concepts/{topic}/{concept}.md)

❌ Violation

```{lang}

// Code showing anti-pattern

```

✅ Correct

```{lang}

// Code showing correct implementation

```

{Any framework-specific considerations}

```

Updating Skills for Three-Layer

When creating or updating skills, add these front matter fields:

```yaml

---

name: skill-name

applies_concepts:

- knowledge/concepts/{topic}/{concept}

uses_implementations:

- knowledge/implementations/{lang}/{file}

---

```

Governance Checklist

Before creating ANY knowledge artifact:

• [ ] Concept exists? If creating implementation, verify concept exists first
• [ ] No code in concept? Concepts must be code-free
• [ ] Links bidirectional? Concept → Implementation, Implementation → Concept
• [ ] INDEX updated? Add to knowledge/concepts/INDEX.md or knowledge/implementations/INDEX.md

---

Create a skill:

```bash

python scripts/init_skill.py pdf-processor --path .claude/skills --template tool

```

Create an agent:

```bash

python scripts/init_agent.py abp-code-reviewer --path .claude/agents --template reviewer --category reviewers

```

Create a command:

```bash

python scripts/init_command.py run-tests --path .claude/commands --template workflow --category tdd

```

1. Decision Pattern

```

User triggers explicitly → COMMAND

Claude auto-detects → SKILL (no isolation) or AGENT (with isolation)

Deterministic on events → HOOK

```

2. Progressive Disclosure

```

Level 1: description (~100 tokens) → Trigger matching

Level 2: SKILL.md body (<5k tokens) → When activated

Level 3: references/ → On-demand deep dives

```

3. Artifact Limits

See [GUIDELINES.md § Size Limits](../../GUIDELINES.md#size-limits) for authoritative limits.

Quick reference: Skills <500, Agents <150, References one level deep.

4. Description Pattern

```yaml

# Good: Third-person with triggers

description: Processes PDF files for text extraction and form filling.

Use when working with PDFs, extracting text, or filling forms.

# Bad: First-person or vague

description: I can help you with documents

```

| Field | Requirements |

|-------|--------------|

| name | Max 64 chars, lowercase, hyphens only, no reserved words (anthropic, claude) |

| description | Max 1024 chars, third-person voice, 3+ trigger scenarios, no XML tags |

| tools | Comma-separated; omitting grants ALL tools (including MCP) |

| model | haiku (fast), sonnet (balanced), opus (powerful) |

| permissionMode | default, acceptEdits, bypassPermissions |

See [GUIDELINES.md § Choosing the Right Tool](../../GUIDELINES.md#choosing-the-right-tool) for the full decision matrix.

Quick reference: Command (user triggers) → Skill (auto, no isolation) → Agent (auto, isolated) → Hook (deterministic events)

Step 1: Identify Type

```

Type Decision Checklist:

• [ ] User invokes with /command? → Command
• [ ] Needs separate context window? → Agent
• [ ] Auto-triggered domain knowledge? → Skill
• [ ] Shell action on tool events? → Hook

```

Step 2: Gather Requirements

Skills: Trigger scenarios (3+), resources needed, primary workflow

Agents: Team role, tools needed (least privilege), permission mode

Commands: Arguments, phases, expected output

Step 3: Initialize

| Type | Command |

|------|---------|

| Skill | python scripts/init_skill.py --template |

| Agent | python scripts/init_agent.py --template --category |

| Command | python scripts/init_command.py --template --category |

Templates:

• Skills: default, tool, workflow, domain, analysis, integration, generator, pattern
• Agents: architect, reviewer, developer, coordinator, specialist
• Commands: review, generate, debug, workflow, git, refactor

Step 4: Test

```

Testing Checklist:

• [ ] Customize all placeholders ([DOMAIN], [TARGET])
• [ ] Test with Haiku - enough guidance?
• [ ] Test with Sonnet - clear and efficient?
• [ ] Test with Opus - not over-explained?
• [ ] Verify triggers activate correctly

```

Claude Code includes built-in agents (cannot be modified):

| Agent | Purpose | Mode |

|-------|---------|------|

| Plan | Research before presenting plan | Read-only, plan mode |

| Explore | Fast codebase search | Read-only (ls, find, cat, head, tail) |

Note: Subagents cannot spawn other subagents.

⚠️ Warning: Omitting tools grants ALL tools including MCP. Always whitelist explicitly.

Full reference: See [GUIDELINES.md § Agents](../../GUIDELINES.md#agents-agents) for tool permissions by role, and [GUIDELINES.md § Hooks](../../GUIDELINES.md#hooks) for hook events.

1. Concise over comprehensive - Claude is smart; add only what it doesn't know
2. Show, don't tell - Examples beat descriptions
3. Third-person descriptions - Required for system prompt injection
4. 3+ trigger scenarios - Specific scenarios in description ensure activation
5. Least privilege tools - Only grant necessary tools
6. One level deep references - No nested references (causes partial reads)
7. Test all models - What works for Opus may need more detail for Haiku
8. Validate before shipping - Run scripts/validate.py --strict

| Pitfall | Detection | Fix |

|---------|-----------|-----|

| Vague triggers | Description <100 chars | Add 3+ specific scenarios |

| Abstract only | No code blocks | Add before/after examples |

| Monolithic | >500 lines | Move to references/ |

| Kitchen sink | Lists 5+ domains | Create specialized artifacts |

| Embedded code in agent | Code blocks in agent | Extract to skill |

| First-person description | "I can help" | Use third-person |

See [references/anti-patterns.md](references/anti-patterns.md) for comprehensive list.

When agents grow >150 lines, extract embedded content to skills, commands, or docs.

Full guide: See [agent-refactoring-guide.md](references/agent-refactoring-guide.md)

For comprehensive agent optimization, see [agent-optimization-patterns.md](references/agent-optimization-patterns.md).

Key techniques:

| Technique | Purpose |

|-----------|---------|

| Semantic skill categorization | Organize skills by METHODOLOGY, DOMAIN, LENS, OUTPUT |

| Explicit workflow pipeline | Declarative GATHER → ANALYZE → REPORT in frontmatter |

| Skill invocation guidance | Phase-to-skill mapping with fallback checks |

| Project-agnostic design | Dynamic context loading from docs/ |

| Output externalization | Dedicated format skill for report templates |

Quick optimization checklist:

```

• [ ] Skills categorized semantically (not alphabetically)
• [ ] Workflow defined as pipeline with phase-to-skill mapping
• [ ] Fallback checks provided for skill failures
• [ ] No hardcoded project names/paths
• [ ] Output template in dedicated skill
• [ ] Quality self-check categorized by concern
• [ ] Agent size <150 lines

```

Agents declare their knowledge profile in YAML front matter to enable validation and discoverability.

See [GUIDELINES.md § Artifact Knowledge Rules](../../GUIDELINES.md#artifact-knowledge-rules) for full governance.

Required Front Matter Fields

| Field | Purpose | Format |

|-------|---------|--------|

| understands | Concepts agent knows | List of paths relative to knowledge/concepts/ |

| applies | Implementations agent uses | List of paths relative to knowledge/implementations/ |

Example

```yaml

---

name: abp-developer

understands:

- solid/srp

- solid/dip

- clean-code/naming

- clean-architecture/layers

applies:

- dotnet/solid

- dotnet/clean-code

---

```

Validation Rules

1. Path validation: All understands paths must exist in knowledge/concepts/INDEX.md
2. Path validation: All applies paths must exist in knowledge/implementations/INDEX.md
3. Wildcard support: Use solid/* to include all concepts in a category
4. Role requirements: Agents must meet minimum counts for their category

Role Requirements

| Role (folder) | understands (min) | applies (min) |

|---------------|---------------------|-----------------|

| reviewers/ | 3 | 1 |

| engineers/ | 2 | 2 |

| architects/ | 3 | 0 |

| specialists/ | 1 | 0 |

Validation Checklist

When creating or updating agents:

• [ ] All understands paths exist in concepts INDEX
• [ ] All applies paths exist in implementations INDEX
• [ ] Agent meets minimum requirements for its role category
• [ ] Skills align with knowledge profile (related domains)

Cross-reference: See [ARTIFACT-KNOWLEDGE-MATRIX.md](../../ARTIFACT-KNOWLEDGE-MATRIX.md) for full coverage.

Track these for artifact quality:

| Metric | Target |

|--------|--------|

| Trigger accuracy | Activates on relevant requests |

| Output consistency | Same quality across similar inputs |

| Model compatibility | Works with Haiku, Sonnet, Opus |

| Line count | Skills <500, Agents <150 |

| Description length | 100-1024 chars with triggers |

See [GUIDELINES.md § Quality Checklists](../../GUIDELINES.md#quality-checklists) for authoritative checklists.

Quick validation:

• [ ] Description: third-person, 100-1024 chars, 3+ triggers
• [ ] Name: lowercase, hyphens, max 64 chars
• [ ] Under line limits (per GUIDELINES.md)
• [ ] Tested with Haiku, Sonnet, and Opus

Command → Agent → Skill

```

/add-feature (command)

└─ Uses backend-architect (agent)

└─ Applies api-design-principles (skill)

```

Skill as Knowledge, Command as Action

```

Rule: "Knowing" = Skill, "Doing" = Command

"Doing with Knowledge" = Command referencing Skills

```

Primary (READ FIRST):

• [.claude/GUIDELINES.md](../../GUIDELINES.md) - Authoritative meta-knowledge for all artifact creation

Skill-Specific:

• [references/skills/skill-types.md](references/skills/skill-types.md) - Archetypes
• [references/agents/agent-categories.md](references/agents/agent-categories.md) - Role definitions
• [references/commands/command-patterns.md](references/commands/command-patterns.md) - Patterns
• [references/anti-patterns.md](references/anti-patterns.md) - What to avoid
• [references/agent-refactoring-guide.md](references/agent-refactoring-guide.md) - Extract from agents
• [references/agent-optimization-patterns.md](references/agent-optimization-patterns.md) - Advanced optimization techniques (skill categorization, workflow pipelines, fallback patterns)

Project Context:

• CLAUDE.md - Project-specific values and quick references