Agent skill

managing-artifacts

Use when generating documents, reports, plans, audits, or deciding where to save output files. Triggers: 'save report', 'write plan', 'where should I put this', 'where does this go', 'output directory', 'save this somewhere'.

View SKILL.md on GitHub Repository
Stars 5
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/axiomantic/spellbook/tree/main/skills/managing-artifacts

SKILL.md

Managing Artifacts

Invariant Principles

  1. Never litter projects: Generated artifacts go to ~/.local/spellbook/, never project directories
  2. Respect shared repos: Multi-contributor projects use fallback paths to avoid polluting the repo
  3. Consistent encoding: Always use project-encoded paths for organization

Standard Directory Structure

~/.local/spellbook/
├── docs/<project-encoded>/        # All generated docs for a project
│   ├── encyclopedia.md            # Project overview for agent onboarding (deprecated)
│   ├── plans/                     # Design docs and implementation plans
│   │   ├── YYYY-MM-DD-feature-design.md
│   │   └── YYYY-MM-DD-feature-impl.md
│   ├── audits/                    # Test audits, code reviews, etc.
│   │   └── auditing-green-mirage-YYYY-MM-DD-HHMMSS.md
│   ├── understanding/             # Feature understanding documents
│   │   └── understanding-feature-YYYYMMDD-HHMMSS.md
│   └── reports/                   # Analysis reports, summaries
│       └── simplify-report-YYYY-MM-DD.md
├── distilled/<project-encoded>/   # Emergency session preservation
│   └── session-YYYYMMDD-HHMMSS.md
└── logs/                          # Operation logs
    └── review-pr-comments-YYYYMMDD.log

Project Encoded Path Generation

bash
# Find outermost git repo (handles nested repos like submodules/vendor)
_outer_git_root() {
  local root=$(git rev-parse --show-toplevel 2>/dev/null)
  [ -z "$root" ] && { echo "NO_GIT_REPO"; return 1; }
  local parent
  while parent=$(git -C "$(dirname "$root")" rev-parse --show-toplevel 2>/dev/null) && [ "$parent" != "$root" ]; do
    root="$parent"
  done
  echo "$root"
}
PROJECT_ROOT=$(_outer_git_root)
PROJECT_ENCODED=$(echo "$PROJECT_ROOT" | sed 's|^/||' | tr '/' '-')
# Result: "Users-alice-Development-myproject"

If NO_GIT_REPO: Ask user to init, or use fallback: ~/.local/spellbook/docs/_no-repo/$(basename "$PWD")/

NEVER Write To

Path Why
<project>/docs/ Project docs are for project documentation
<project>/plans/ Reserved for project planning
<project>/reports/ Reserved for project reports
<project>/*.md Except CLAUDE.md when explicitly requested

Project-Specific CLAUDE.md

Fallback Lookup

If project has no CLAUDE.md, check: ~/.local/spellbook/docs/<project-encoded>/CLAUDE.md

Open Source Project Handling

Detection (any of):

  • Has upstream git remote
  • Multiple authors (git shortlog -sn | wc -l > 1)
  • Has CONTRIBUTING.md
  • Is a fork

When user asks to "add X to CLAUDE.md" for such a project:

  1. Detect if open source/multi-contributor
  2. Write to fallback location instead
  3. Inform user: "This appears to be a shared repository. Added to ~/.local/spellbook/docs/..."

Quick Reference

Artifact Type Location
Design docs ~/.local/spellbook/docs/<project>/plans/YYYY-MM-DD-feature-design.md
Impl plans ~/.local/spellbook/docs/<project>/plans/YYYY-MM-DD-feature-impl.md
Audits ~/.local/spellbook/docs/<project>/audits/
Reports ~/.local/spellbook/docs/<project>/reports/
Encyclopedia (deprecated) ~/.local/spellbook/docs/<project>/encyclopedia.md
Session distill ~/.local/spellbook/distilled/<project>/
Logs ~/.local/spellbook/logs/

<FINAL_EMPHASIS> Every artifact you generate belongs in ~/.local/spellbook/, not in the project. A clean project is a professional project. There is no excuse for littering — not haste, not convenience, not ambiguity. </FINAL_EMPHASIS>

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

axiomantic/spellbook

spellbook-auditing

Meta-audit skill for spellbook development. Spawns parallel subagents to factcheck docs, optimize instructions, find token savings, and identify MCP candidates. Produces actionable report.

5 2
Explore
axiomantic/spellbook

documentation-updates

Use after modifying library skills, library commands, or agents to ensure CHANGELOG, README, and docs are updated

5 2
Explore
axiomantic/spellbook

project-encyclopedia

[DEPRECATED] Use project-level AGENTS.md files instead. Previously used for first-session codebase onboarding and persistent glossary creation.

5 2
Explore
axiomantic/spellbook

reviewing-impl-plans

Use when reviewing implementation plans before execution. Triggers: 'is this plan solid', 'review the plan', 'check before I start building', 'anything missing from this plan', 'will this plan work', 'audit the implementation plan'. NOT for: reviewing design documents (use reviewing-design-docs) or creating plans (use writing-plans).

5 2
Explore
axiomantic/spellbook

session-resume

Session resume protocol and session repairs handling. Loaded when spellbook_session_init returns resume_available: true, or when session_init returns a repairs array. Triggers: 'resume', 'continue', 'where were we', session resume, session repairs.

5 2
Explore
axiomantic/spellbook

brainstorming

Use when exploring design approaches, generating ideas, or making architectural decisions. Triggers: 'explore options', 'what are the tradeoffs', 'how should I approach', 'let's think through', 'sketch out an approach', 'I need ideas for', 'how would you structure', 'what are my options'. Also invoked by develop when design decisions are needed.

5 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results