| name | asta-documents |
| description | Local document metadata index for scientific documents |
Use this skill when the user asks to store a document "in Asta" or retrieve "from Asta". Use it when the
user references an "Asta document" or anything with an asta:// URI.
This skill provides complete document management functionality for tracking research papers, documentation, and resources using the asta-documents CLI.
What it does: Track document metadata (URLs, summaries, tags) in a local index. Think of it as a smart bookmark manager with powerful search capabilities.
# Install globally using uv
uv tool install git+https://github.com/allenai/asta-resource-repo.git
Prerequisites: Python 3.10+ and uv package manager
Verify installation with asta-documents --help
Add --json flag to any command for machine-readable output.
# List documents
asta-documents list
asta-documents list --tags="ai,research"
# Search document summaries
asta-documents search "query"
# Search by specific field
asta-documents search "title words" --name
asta-documents search "ai,nlp" --tags
asta-documents search ".year > 2020" --extra
# Add document
asta-documents add <url> --name="Title" --summary="Description" --tags="tag1,tag2" --extra='{"author": "Smith et al", "year": 2024, "venue": "NeurIPS"}'
# Get document metadata
asta-documents get <uuid>
# Update document
asta-documents update <uuid> --name="New Title" --tags="new,tags"
# Fetch document content
asta-documents fetch <uuid> -o /tmp/document.pdf
# Manage tags
asta-documents add-tags <uuid> --tags="new,tags"
asta-documents remove-tags <uuid> --tags="old,tags"
# Cache management
asta-documents cache list
asta-documents cache stats
asta-documents cache clean --days 7
# Summary information (document counts)
asta-documents show
Always use the command line interface for all operations to ensure proper index management and caching. Avoid direct read/write operations on the index file.
The index stores metadata only. The content of a document is retrievable via its URL. The fetch command retrieves the content and caches it locally for future use.
Fetch to file (with automatic caching):
asta-documents fetch <uuid> -o /tmp/document.pdf
List cached items:
asta-documents cache list
Show cache statistics:
asta-documents cache stats
Clean old cache entries:
# Remove items older than N days
asta-documents cache clean --days 14
Clear entire cache:
asta-documents cache clear
asta-documents cache clear -y # Skip confirmation
Show specific item details:
asta-documents cache info <hash>
# Add research paper
asta-documents add https://arxiv.org/pdf/1706.03762.pdf \
--name="Attention Is All You Need" \
--summary="Seminal paper introducing Transformer architecture" \
--tags="ai,research,nlp,transformers" \
--mime-type="application/pdf" \
--extra='{"author": "Vaswani et al", "year": 2017, "venue": "NeurIPS"}'
# Search papers by tag
asta-documents search "transformers" --tags
# Search for relevant documents
asta-documents search "transformer architecture" --show-scores
# Get metadata for top result (using UUID from search results)
asta-documents get 6MNxGbWGRC
# Fetch content
asta-documents fetch 6MNxGbWGRC -o /tmp/paper.pdf -q
# Read with PDF support
# Read(/tmp/paper.pdf)
# Search and extract UUIDs
RESULTS=$(asta-documents search "query" --json)
# Get first UUID (example with Python)
UUID=$(echo "$RESULTS" | python3 -c "import sys,json; results=json.load(sys.stdin); print(results[0]['result']['uuid'] if results else '')")
# Fetch that document
asta-documents fetch "$UUID" -o result.pdf
# List documents with old tag
DOCS=$(asta-documents list --tags="old-tag" --json)
# For each, remove old tag and add new
for uuid in $(echo "$DOCS" | python3 -c "import sys,json; print('\\n'.join([d['uuid'] for d in json.load(sys.stdin)]))"); do
asta-documents remove-tags "$uuid" --tags="old-tag"
asta-documents add-tags "$uuid" --tags="new-tag"
done
# Get current metadata (using UUID)
asta-documents get 6MNxGbWGRC
# Update multiple fields
asta-documents update 6MNxGbWGRC \
--name="Updated Title" \
--summary="Updated summary with more details" \
--tags="updated,revised,2025"
# Check cache usage
asta-documents cache stats
# List what's cached
asta-documents cache list
# Remove old entries if cache is large
asta-documents cache clean --days 7
# Verify cache reduction
asta-documents cache stats
Asta uses different search strategies optimized for each document field:
--name (Name search):
asta-documents search "Attention" --name--tags (Tag search):
asta-documents search "ai,nlp" --tags--summary (Summary search, default):
asta-documents search "papers about transformers"--extra (Extra metadata search):
>, >=, <, <=, ==, containsasta-documents search ".year > 2020" --extraasta-documents search ".author contains Smith" --extraasta-documents search ".venue == NeurIPS" --extraHuman-readable (default):
JSON (--json flag):
Verbose (-v flag for list):
-q suppresses progress messages"asta-documents: command not found"
uv tool list | grep astaexport PATH="$HOME/.local/bin:$PATH"uv tool install --reinstall git+https://github.com/allenai/asta-resource-repo.git"Document not found"
asta-documents list --json | grep <partial-uri>.asta/documents/index.yaml"Fetch failed"
curl -I <url>--force"Search returns no results"
asta-documents search "keyword" --nameasta-documents search "tag" --tagsasta-documents list"Cache is large"
asta-documents cache statsasta-documents cache clean --days 7asta-documents cache clear -yUpdate the CLI tool:
uv tool install --reinstall git+https://github.com/allenai/asta-resource-repo.git
Update the skill:
curl -o ~/.claude/skills/asta-documents.md https://raw.githubusercontent.com/allenai/asta-resource-repo/main/skills/asta-documents.md