axiomantic/managing-artifacts
skills/managing-artifacts/SKILL.md
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'.
$ install --global
skillsauthnpx skillsauth add axiomantic/spellbook managing-artifactsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 20, 2026, 3:20 PM1.8s1 file scanned
SKILL.md
- name:
- managing-artifacts
- description:
- 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'.
Managing Artifacts
<ROLE> Artifact Organization Specialist. Your reputation depends on keeping projects clean and artifacts findable. Littering project directories with generated files is a cardinal sin. </ROLE> <CRITICAL> ALL generated documents, reports, plans, and artifacts MUST be stored outside project directories. This prevents littering projects with generated files and keeps artifacts organized centrally. </CRITICAL>Invariant Principles
- Never litter projects: Generated artifacts go to
~/.local/spellbook/, never project directories - Respect shared repos: Multi-contributor projects use fallback paths to avoid polluting the repo
- 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
# 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
<RULE> For multi-contributor projects, NEVER add instructions to `<project>/CLAUDE.md`. Write to `~/.local/spellbook/docs/<project-encoded>/CLAUDE.md` instead. </RULE>Detection (any of):
- Has
upstreamgit 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:
- Detect if open source/multi-contributor
- Write to fallback location instead
- 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>
Related Skills
axiomantic/writing-skills
testing
VerifiedTrustedCommunity
Use when creating new skills, editing existing skills, or verifying skills work before deployment. Triggers: 'write a skill', 'new skill', 'create a skill', 'skill doesn't work', 'skill isn't firing', 'edit skill', 'skill quality'. NOT for: general prompt improvement (use instruction-engineering) or command creation (use writing-commands).
5SKILL.mdUpdated Apr 3, 2026
axiomantic/writing-plans
development
VerifiedTrustedCommunity
Use when you have a spec, design doc, or requirements and need a detailed implementation plan before coding. Triggers: 'write a plan', 'create implementation plan', 'plan this out', 'break this down into steps', 'convert design to tasks', 'implementation order'. Also invoked by develop during planning. NOT for: reviewing existing plans (use reviewing-impl-plans).
5SKILL.mdUpdated Apr 3, 2026
axiomantic/writing-commands
testing
VerifiedTrustedCommunity
Use when creating new commands, editing existing commands, or reviewing command quality. Triggers: 'write command', 'new command', 'create a command', 'review command', 'fix command', 'command doesn't work', 'add a slash command'. NOT for: skill creation (use writing-skills).
5SKILL.mdUpdated Apr 3, 2026
axiomantic/verifying-hunches
development
VerifiedTrustedCommunity
Use when about to claim discovery during debugging. Triggers: "I found", "this is the issue", "I think I see", "looks like the problem", "that's why", "the bug is", "root cause", "culprit", "smoking gun", "aha", "got it", "here's what's happening", "the reason is", "causing the", "explains why", "mystery solved", "figured it out", "the fix is", "should fix", "this will fix". Also invoked by debugging, scientific-debugging, systematic-debugging before any root cause claim.
5SKILL.mdUpdated Apr 3, 2026