Artifacts: Creating and Managing

Quick Start
Triggers
Purpose
When to Use Artifacts
Directory Structure
File Naming Conventions
Core Rules
Category Definitions
Helper Scripts
Integration Pattern
Supporting Files
Best Practices
Red Flags to Avoid

Quick Start

See scripts/create_adr.py for creating ADRs.

See scripts/create_research_topic.py for creating research topics.

See scripts/create_implementation_plan.py for creating implementation plans.

Triggers

Trigger with phrases like:

"create an ADR"
"create ADR for [decision]"
"research [topic]"
"create research topic"
"spike investigation on [topic]"
"create spike for [investigation]"
"implementation plan for [feature]"
"create analysis"
"analyze [subject]"
"document decision"
"plan implementation"

Purpose

Standardizes how artifacts are created and organized within

.claude/artifacts/

directory. Artifacts are temporary work products that support development but don't belong in version control or permanent documentation.

When to Use This Skill

Use when asked to:

Document architectural decisions ("create an ADR for event sourcing")
Research technical topics ("research GraphQL libraries for React")
Plan feature implementations ("create implementation plan for 2FA")
Conduct time-boxed investigations ("spike on OAuth2 integration")
Analyze existing code or architecture ("analyze performance bottlenecks")

Do NOT use when:

Creating permanent documentation (use
```
docs/
```
directory instead)
Writing source code (use
```
src/
```
directory)
User needs quick inline answers (respond directly in conversation)

When to Use Artifacts

Use artifacts when:

Conducting research ("research GraphQL libraries")
Creating spikes ("spike on authentication approaches")
Writing analysis ("analyze performance bottlenecks")
Documenting decisions (ADRs)
Planning implementations
Capturing session notes
Recording investigation results

Don't use artifacts for:

Permanent documentation (use
```
docs/
```
instead)
Source code (use
```
src/
```
instead)
Tests (use
```
tests/
```
instead)
Configuration (use config files)

Directory Structure

.claude/artifacts/
├── YYYY-MM-DD/                    # Date-based organization
│   ├── research/                  # Research topics
│   │   └── topic-name.md
│   ├── spikes/                    # Technical spikes
│   │   └── spike-name.md
│   ├── analysis/                  # Code/architecture analysis
│   │   └── analysis-name.md
│   ├── plans/                     # Implementation plans
│   │   └── plan-name.md
│   ├── sessions/                  # Session notes
│   │   └── session-name.md
│   └── adr/                       # Architecture Decision Records
│       └── NNN-decision-name.md
└── completed/                     # Archived artifacts
    └── adr/
        └── NNN-decision-name.md

File Naming Conventions

Research topics:

.claude/artifacts/YYYY-MM-DD/research/topic-name.md
Example: .claude/artifacts/2025-12-24/research/graphql-libraries.md

Spikes:

.claude/artifacts/YYYY-MM-DD/spikes/spike-name.md
Example: .claude/artifacts/2025-12-24/spikes/oauth2-integration.md

Analysis:

.claude/artifacts/YYYY-MM-DD/analysis/analysis-name.md
Example: .claude/artifacts/2025-12-24/analysis/performance-bottlenecks.md

Implementation plans:

.claude/artifacts/YYYY-MM-DD/plans/feature-name-plan.md
Example: .claude/artifacts/2025-12-24/plans/user-authentication-plan.md

ADRs:

.claude/artifacts/YYYY-MM-DD/adr/NNN-decision-title.md
Example: .claude/artifacts/2025-12-24/adr/001-use-event-sourcing.md

Core Rules

Date-based organization - All artifacts under
```
YYYY-MM-DD/
```
directory
Kebab-case names - Use hyphens, lowercase, no spaces
Category folders - research/, spikes/, analysis/, plans/, adr/
Markdown format - All artifacts are .md files
Templated creation - Use helper scripts for consistency
Completion tracking - Move to
```
completed/
```
when done

Category Definitions

Research

Purpose: Investigate libraries, tools, or approaches

Template: See templates/research_template.md

Example usage: "Research GraphQL client libraries for React"

Spikes

Purpose: Time-boxed technical investigation

Template: Spike template not yet created (use research template as starting point)

Example usage: "Spike on OAuth2 integration with existing auth system"

Analysis

Purpose: Investigate existing code/architecture

Template: Analysis template not yet created (use research template as starting point)

Example usage: "Analyze performance bottlenecks in API handlers"

Plans

Purpose: Document implementation approach

Template: See templates/implementation_plan_template.md

Example usage: "Plan implementation of two-factor authentication"

ADRs (Architecture Decision Records)

Purpose: Document architectural decisions

Template: See templates/adr_template.md

Example usage: "ADR 001: Use Event Sourcing for Audit Trail"

Helper Scripts

All scripts located in

.claude/skills/artifacts-creating-and-managing/scripts/

create_adr.py

See scripts/create_adr.py for full script.

Required: --title, --status, --context Optional: --decision, --consequences

create_research_topic.py

See scripts/create_research_topic.py for full script.

Required: --topic, --objective Optional: --questions (multiple)

create_spike.py

Note: Spike script not yet created. Use create_research_topic.py as alternative.

create_analysis.py

Note: Analysis script not yet created. Use create_research_topic.py as alternative.

create_implementation_plan.py

See scripts/create_implementation_plan.py for full script.

Required: --feature, --overview Optional: --steps (multiple), --risks

Integration Pattern

Typical workflow:

Create artifact: Use helper scripts (see Helper Scripts section)
Work on artifact:
- Add findings, analysis, or decisions
- Reference code, documentation, or other artifacts
- Update as investigation progresses
Complete artifact:
- Mark as complete (status: accepted/completed)
- Move to
```
completed/
```
  if ADR
- Reference in code or documentation
- Archive or delete if temporary
Cross-reference:
- Link from code comments:
```
// See: .claude/artifacts/YYYY-MM-DD/research/topic.md
```
- Link from documentation:
```
docs/
```
  references artifacts
- Link between artifacts: Related ADRs reference each other

Usage Examples

See examples/ directory for detailed usage examples including:

Research library workflow
ADR creation workflow
Implementation plan workflow

Expected Outcomes

Successful Artifact Creation:

Artifact created in correct location (

.claude/artifacts/YYYY-MM-DD/{category}/

)

File follows naming conventions (kebab-case)
Template applied with placeholders filled
Ready for content addition

Completed Artifact:

Decision documented (for ADRs)
Research findings captured (for research)
Implementation steps defined (for plans)
Cross-referenced in code/docs where appropriate
Moved to
```
completed/
```
if applicable

Supporting Files

templates/ - Markdown templates:
- adr-template.md
- research-template.md
- spike-template.md
- analysis-template.md
- plan-template.md
scripts/ - Helper scripts:
- create_adr.py
- create_research_topic.py
- create_spike.py
- create_analysis.py
- create_implementation_plan.py
- list_artifacts.py (find all artifacts)
- archive_artifact.py (move to completed/)

Best Practices

Use templates - Scripts ensure consistency
Date organization - Easy to find recent artifacts
Descriptive names - Clear purpose from filename
Complete artifacts - Don't leave them half-finished
Cross-reference - Link artifacts to code/docs
Archive when done - Move completed ADRs to
```
completed/
```
Delete temporary artifacts - Don't accumulate unnecessary files
Update status - Keep artifact status current

Red Flags to Avoid

Creating artifacts in wrong location - Always use
```
.claude/artifacts/
```
Skipping date folder - All artifacts under
```
YYYY-MM-DD/
```
Mixed case names - Use kebab-case consistently
No category folder - Put in research/, spikes/, etc.
Creating without template - Use helper scripts
Leaving artifacts incomplete - Finish or delete
Not archiving ADRs - Move completed ADRs to
```
completed/
```
Creating permanent docs as artifacts - Use
```
docs/
```
for permanent documentation

Key principle: Artifacts are temporary work products with standardized structure. They support development but aren't permanent documentation.

Remember: Use helper scripts for consistency, organize by date, and archive/delete when complete.

artifacts-creating-and-managing

NPX Install

Tags

SKILL.md Content