⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
your-domain-name
Brief description of what this skill does
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Skill Template
This directory contains template files for creating new skills. Use these as a starting point when building a new domain skill.
Files
| File | Purpose |
|---|---|
SKILL.md | Template for skill documentation (what Claude reads) |
template.py | Template for CLI script (TypeDB operations) |
schema.tql | Template for TypeDB schema (data model) |
Quick Start
-
Copy this directory:
cp -r .claude/skills/_template .claude/skills/<your-domain> -
Rename the script:
mv .claude/skills/<your-domain>/template.py .claude/skills/<your-domain>/<your-domain>.py -
Edit the schema (
schema.tql):- Replace
DOMAINwith your domain name - Define your attributes, entities, and relations
- Copy to
local_resources/typedb/namespaces/<your-domain>.tql
- Replace
-
Edit the script (
<your-domain>.py):- Replace
DOMAINwith your domain name - Implement your commands
- Add argparse subcommands
- Replace
-
Edit
SKILL.md:- Fill in the frontmatter
- Document your commands
- Describe the sensemaking workflow
-
Load the schema:
docker exec -i alhazen-typedb /opt/typedb-all-linux-x86_64/typedb console --server=localhost:1729 << 'EOF' transaction alhazen_notebook schema write source /schema/namespaces/<your-domain>.tql commit EOF -
Test:
uv run python .claude/skills/<your-domain>/<your-domain>.py --help
Checklist
Before your skill is complete:
- Schema loaded into TypeDB
- Script has
--helpfor all commands - Script outputs JSON to stdout
- SKILL.md has complete command reference
- SKILL.md documents sensemaking workflow
- Tested with Claude Code
Architecture Reference
See the wiki page Skill-Architecture for detailed documentation on the three-component architecture.
// HOW IT'S BUILT
// FILES
8 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/_template/SKILL.md2.1 KBbdfcab23b8feupstream ↗
--- name: your-domain-name description: Brief description of what this skill does --- # Your Domain Name Skill Use this skill to [describe primary use case]. Claude acts as [describe Claude's role in this domain]. **When to use:** [Triggers: "ingest [item]", "analyze [item]", "show [entity]", ...] ## Prerequisites - TypeDB must be running: `make db-start` - Dependencies installed: `uv sync --all-extras` (from project root) - Schema loaded: run `make build-db` after adding your `schema.tql` ## Environment Variables - `TYPEDB_HOST`: TypeDB server (default: localhost) - `TYPEDB_PORT`: TypeDB port (default: 1729) - `TYPEDB_DATABASE`: Database name (default: alhazen_notebook) ## Quick Start ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py list-entities ``` ## Schema Gap Recognition During sensemaking, if you encounter a concept, relationship, or entity type that has no place in the current TypeDB schema, that is a **schema gap** — a signal for schema evolution, not a failure. When you notice a schema gap: 1. Complete as much as possible with the current schema (partial knowledge > none) 2. Immediately file a gap issue: ```bash gh issue create --repo <owner/name> \ --title "Gap [moderate][entity-schema]: <one-sentence summary>" \ --body $'## What was missing\n<the concept you tried to represent>\n\n## What broke\n<which TypeDB entity/relation/attribute is absent>\n\n## Suggested fix\n<proposed TypeQL addition, or unknown>' \ --label "gap:open" ``` **Examples of schema gaps:** - A paper has a methodology section but there's no `methodology` attribute on `scilit-paper` - A job posting mentions a work arrangement type that isn't in the schema - A disease has a phenotype frequency that can't be attached to the current relation Use `--dry-run` first to review the issue before filing it. ## Command Output Pattern `uv run` emits a `VIRTUAL_ENV` warning to stderr. Always use `2>/dev/null` when piping output to a JSON parser — never `2>&1`, which merges the warning into stdout and breaks JSON parsing. **Before executing any commands, read `USAGE.md` in this directory for the complete command reference, workflows, and data model.**skills/_template/README.md1.9 KB4e3690163962upstream ↗
# Skill Template This directory contains template files for creating new skills. Use these as a starting point when building a new domain skill. ## Files | File | Purpose | |------|---------| | `SKILL.md` | Template for skill documentation (what Claude reads) | | `template.py` | Template for CLI script (TypeDB operations) | | `schema.tql` | Template for TypeDB schema (data model) | ## Quick Start 1. **Copy this directory:** ```bash cp -r .claude/skills/_template .claude/skills/<your-domain> ``` 2. **Rename the script:** ```bash mv .claude/skills/<your-domain>/template.py .claude/skills/<your-domain>/<your-domain>.py ``` 3. **Edit the schema (`schema.tql`):** - Replace `DOMAIN` with your domain name - Define your attributes, entities, and relations - Copy to `local_resources/typedb/namespaces/<your-domain>.tql` 4. **Edit the script (`<your-domain>.py`):** - Replace `DOMAIN` with your domain name - Implement your commands - Add argparse subcommands 5. **Edit `SKILL.md`:** - Fill in the frontmatter - Document your commands - Describe the sensemaking workflow 6. **Load the schema:** ```bash docker exec -i alhazen-typedb /opt/typedb-all-linux-x86_64/typedb console --server=localhost:1729 << 'EOF' transaction alhazen_notebook schema write source /schema/namespaces/<your-domain>.tql commit EOF ``` 7. **Test:** ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py --help ``` ## Checklist Before your skill is complete: - [ ] Schema loaded into TypeDB - [ ] Script has `--help` for all commands - [ ] Script outputs JSON to stdout - [ ] SKILL.md has complete command reference - [ ] SKILL.md documents sensemaking workflow - [ ] Tested with Claude Code ## Architecture Reference See the wiki page [Skill-Architecture](https://github.com/GullyBurns/skillful-alhazen/wiki/Skill-Architecture) for detailed documentation on the three-component architecture.skills/_template/pipelines/pipeline_template.py8.5 KBccf3c5d2d7d4upstream ↗
""" <YourSkill> Assessment Pipeline -- Hamilton DAG This is the canonical Analysis phase pipeline template for TypeDB-backed curation skills. Copy and adapt for your skill's analysis challenge. Nodes: fetch_records(investigation_id) -> raw list of dicts from TypeDB parse_records(fetch_records) -> List[EntityAssessment] (Pydantic-validated) table_data(parse_records) -> JSON string (stored in TypeDB analysis.content) plot_code(parse_records) -> Observable Plot JS expression (stored in TypeDB analysis.plot-code) Node graph: fetch_records(investigation_id) | parse_records() / \\ table_data() plot_code() Register via: <skill>.py add-pipeline \\ --investigation <ID> \\ --title "My Analysis" \\ --analysis-type pipeline-plot \\ --pipeline-script "@skills/<skill>/pipelines/pipeline_template.py" \\ --pipeline-config '{"outputs":["plot_code","table_data"],"inputs":{"investigation_id":"<ID>"},"env_inputs":{}}' Run via: <skill>.py run-pipeline --id <analysis-id> Schema evolution: add Optional fields to Pydantic models and re-run -- no data migration needed. """ from __future__ import annotations import json import os import re import sys from pathlib import Path from typing import Optional # Uncomment and update once you have defined your Pydantic models: # sys.path.insert(0, str(Path(__file__).parent.parent)) # from eval_models import EntityAssessment, DimensionScores, EntityCategory # ── CONFIGURATION ───────────────────────────────────────────────── TYPEDB_HOST = os.environ.get("TYPEDB_HOST", "localhost") TYPEDB_PORT = int(os.environ.get("TYPEDB_PORT", 1729)) TYPEDB_DATABASE = os.environ.get("TYPEDB_DATABASE", "alh_core") TYPEDB_PASSWORD = os.environ.get("TYPEDB_PASSWORD", "password") # Keyword -> dimension field mapping for score table parsing. # The sensemaking agent writes criterion labels that may vary slightly across runs. # List keywords that should map to each dimension field. DIMENSION_KEYWORDS: list[tuple[list[str], str]] = [ (["dimension_a", "alias_a"], "dimension_a"), (["dimension_b", "alias_b"], "dimension_b"), ] # Regex: matches a markdown table row like "| criterion | 2 | explanation |" _SCORE_ROW_RE = re.compile( r"^\s*\|\s*([^|]+?)\s*\|\s*(\d)\s*[/|]", re.MULTILINE, ) # ── HAMILTON NODES ───────────────────────────────────────────────── def fetch_records(investigation_id: str) -> list[dict]: """ Fetch all entities + their assessment notes from TypeDB. Returns a list of dicts with keys: entity_id, entity_name, note_content (str or None). Adapt the TypeQL query to match your skill's schema. """ from typedb.driver import Credentials, DriverOptions, TransactionType, TypeDB driver = TypeDB.driver( f"{TYPEDB_HOST}:{TYPEDB_PORT}", Credentials("admin", TYPEDB_PASSWORD), DriverOptions(is_tls_enabled=False), ) records = [] try: # Step 1: get all entities in scope with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: entities = list(tx.query(f''' match $ctx isa <your-collection-type>, has id "{investigation_id}"; $ent isa <your-entity-type>, has id $ent_id, has name $ent_name; (investigation: $ctx, system: $ent) isa investigated-in; fetch {{ "entity_id": $ent_id, "entity_name": $ent_name }}; ''').resolve()) for ent in entities: eid = ent["entity_id"] content = None # Step 2: fetch the assessment note for each entity with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: notes = list(tx.query(f''' match $ent isa <your-entity-type>, has id "{eid}"; $note isa note, has topic "assessment", has content $content; (subject: $ent, note: $note) isa aboutness; fetch {{ "content": $content }}; ''').resolve()) if notes: content = notes[0].get("content") records.append({ "entity_id": eid, "entity_name": ent["entity_name"], "note_content": content, }) finally: driver.close() return records def parse_records(fetch_records: list[dict]) -> list[dict]: """ Parse raw records into validated assessment dicts. Once you define your Pydantic models, replace `list[dict]` with `list[EntityAssessment]` and uncomment the Pydantic validation block. """ results = [] for record in fetch_records: eid = record["entity_id"] ename = record["entity_name"] content: Optional[str] = record.get("note_content") warnings: list[str] = [] # Initialise dimension scores to 0 dim_scores: dict[str, int] = {field: 0 for _, field in DIMENSION_KEYWORDS} if content is None: warnings.append("no assessment note found; all scores default to 0") else: rows = _SCORE_ROW_RE.findall(content) if not rows: warnings.append( "assessment note has no parseable score table; all scores default to 0" ) else: found_dims: set[str] = set() for criterion_text, score_str in rows: criterion_lower = criterion_text.lower() for keywords, field in DIMENSION_KEYWORDS: if any(kw in criterion_lower for kw in keywords): dim_scores[field] = int(score_str) found_dims.add(field) break missing = set(dim_scores.keys()) - found_dims if missing: warnings.append( f"dimensions not found in table (defaulted to 0): {sorted(missing)}" ) total = sum(dim_scores.values()) # Replace with Pydantic validation once models are defined: # assessment = EntityAssessment( # id=eid, name=ename, # scores=DimensionScores(**dim_scores), # parse_warnings=warnings, # ) # results.append(assessment.model_dump(mode="json")) results.append({ "id": eid, "name": ename, "scores": {**dim_scores, "total": total}, "parse_warnings": warnings, }) # Sort by total score descending results.sort(key=lambda r: -r["scores"]["total"]) return results def table_data(parse_records: list[dict]) -> list[dict]: """ Return validated assessments as a list of dicts. run-pipeline serialises this via json.dumps() into TypeDB analysis.content. The dashboard then JSON.parse()s it back into the `data` variable for the plot. """ return parse_records def plot_code(parse_records: list[dict]) -> str: """ Return an Observable Plot JS expression. Stored in TypeDB analysis.plot-code. The dashboard evaluates this with `data` bound to the parsed table_data JSON array and `Plot` bound to the Observable Plot library. Replace this placeholder with your actual visualization. """ return r""" Plot.plot({ width: 700, height: 400, marks: [ Plot.barY(data, { x: "name", y: d => d.scores?.total ?? 0, fill: "steelblue", tip: true }), Plot.ruleY([0]) ], x: {tickRotate: -45, label: null}, y: {label: "Total score"} }) """.strip() # ── RUNNER (called by run-pipeline) ─────────────────────────────── if __name__ == "__main__": import hamilton.driver as hd investigation_id = os.environ.get("INVESTIGATION_ID", "") if not investigation_id: print(json.dumps({"success": False, "error": "INVESTIGATION_ID env var not set"})) sys.exit(1) dr = hd.Builder().with_modules(sys.modules[__name__]).build() outputs = dr.execute( ["table_data", "plot_code"], inputs={"investigation_id": investigation_id}, ) preview = { k: (v[:200] + "...") if isinstance(v, str) and len(v) > 200 else v for k, v in outputs.items() } print(json.dumps({"success": True, "outputs": preview}))skills/_template/schema.tql3.6 KB4a69dc8da983upstream ↗
# ============================================================================= # [DOMAIN NAME] NAMESPACE - TypeDB 3.x Schema Extension # ============================================================================= # Domain-specific subtypes for [description]. # Namespace prefix: DOMAIN-* # ALL entity, relation, and attribute types below MUST start with "DOMAIN-" # This prefix is declared in skill.yaml -> schema.namespace # ============================================================================= define # ----------------------------------------------------------------------------- # ATTRIBUTE TYPES - Domain Specific # ----------------------------------------------------------------------------- # TODO: Define your domain-specific attributes # Pattern: attribute DOMAIN-attr-name, value [string|integer|double|boolean|datetime]; # URL attributes # domain-url sub attribute, value string; # Status/state attributes # domain-status sub attribute, value string; # Measurement/score attributes # domain-score sub attribute, value double; # Date attributes # domain-date sub attribute, value datetime; # ----------------------------------------------------------------------------- # ENTITY TYPES - Things # ----------------------------------------------------------------------------- # TODO: Define your primary entity types # Pattern: domain-thing sub domain-thing, # owns domain-attribute, # plays domain-relation:role; # DOMAIN-ENTITY - Primary thing you track # domain-entity sub domain-thing, # owns domain-url, # owns domain-status, # plays domain-relation:role1; # ----------------------------------------------------------------------------- # ENTITY TYPES - Artifacts (raw captured content) # ----------------------------------------------------------------------------- # TODO: Define artifact types for raw content storage # Pattern: domain-artifact-type sub artifact; # DOMAIN-CONTENT - Raw content from source # domain-content sub artifact; # ----------------------------------------------------------------------------- # ENTITY TYPES - Fragments (extracted pieces) # ----------------------------------------------------------------------------- # TODO: Define fragment types for extracted pieces # Pattern: domain-fragment sub fragment, # owns fragment-specific-attribute, # plays domain-relation:role; # DOMAIN-FRAGMENT - Extracted piece of content # domain-fragment sub fragment, # owns domain-attribute, # plays domain-relation:role2; # ----------------------------------------------------------------------------- # ENTITY TYPES - Notes (Claude's analysis) # ----------------------------------------------------------------------------- # TODO: Define note types for different kinds of analysis # Pattern: domain-note-type sub note, # owns note-specific-attribute; # DOMAIN-ANALYSIS-NOTE - Claude's analysis # domain-analysis-note sub note, # owns domain-score; # DOMAIN-RESEARCH-NOTE - Research findings # domain-research-note sub note; # ----------------------------------------------------------------------------- # RELATION TYPES - Domain Specific # ----------------------------------------------------------------------------- # TODO: Define relations between your entities # Pattern: domain-relation sub relation, # relates role1, # relates role2; # DOMAIN-RELATION - Links entity1 to entity2 # domain-relation sub relation, # relates role1, # relates role2; # ============================================================================= # END [DOMAIN NAME] NAMESPACE # =============================================================================skills/_template/schema/eval_schema_template.yaml3.6 KB805ca36578feupstream ↗
id: https://sciknow.io/<your-skill>-eval-schema name: <your-skill>-eval-schema description: > Schema for evaluating <domain entities> on curation dimensions. Extend by adding optional fields -- existing records stay valid (additive evolution). Rename this file and update the id/name prefixes for your skill. prefixes: linkml: https://w3id.org/linkml/ meval: https://sciknow.io/<your-skill>-eval/ default_prefix: meval default_range: string imports: - linkml:types # ── TYPES ───────────────────────────────────────────────────────── # Score is the canonical dimension score type used across curation skills. # All six standard dimensions use 0-3 integer scores. types: Score: uri: xsd:integer base: int description: Integer 0-3 (0=none, 1=partial, 2=substantial, 3=full) minimum_value: 0 maximum_value: 3 # ── ENUMERATIONS ────────────────────────────────────────────────── # Add domain-specific enumerations here. Example: enums: EntityCategory: description: High-level category for the thing being assessed permissible_values: tool: description: A deployed software tool benchmark: description: An evaluation benchmark paper: description: A research paper without a deployed artifact # ── CLASSES ─────────────────────────────────────────────────────── classes: DimensionScores: description: > Scores on the curation assessment dimensions. Replace dimension_a / dimension_b with your actual dimensions. Add a model_validator in the Pydantic implementation to compute `total`. attributes: dimension_a: range: Score required: true description: First dimension -- replace with your dimension name and description dimension_b: range: Score required: true description: Second dimension -- replace with your dimension name and description total: range: integer description: Sum of all dimension scores (derived -- computed in Pydantic model_validator) ifabsent: int(0) EntityAssessment: description: > Complete assessment record for one entity. One record per entity in the skill's knowledge base. This is the top-level unit of analysis -- a row in the visualization. tree_root: true attributes: id: identifier: true range: string description: Stable TypeDB entity id (e.g. trs-xxxxx or your-entity-xxxxx) name: required: true range: string description: Display name category: required: true range: EntityCategory description: High-level category (replace EntityCategory with your enum) scores: required: true range: DimensionScores inlined: true description: Scores on the curation assessment dimensions tags: multivalued: true range: string description: Free-form classification tags assessment_summary: range: string description: Free-text synthesis drawn from sensemaking notes parse_warnings: multivalued: true range: string description: > Warnings emitted during score parsing. Populated when notes are missing or score tables are not found. Use for data quality tracking.skills/_template/skill.yaml1.0 KB1cf755750505upstream ↗
name: DOMAIN description: "Brief description of what this skill does" license: Apache-2.0 compatibility: "TypeDB 3.x" # Core files script: template.py schema: schema.tql # Schema namespace — all types in schema.tql must start with this prefix schema: namespace: DOMAIN # e.g., jobhunt, tech-recon, scilit depends_on: [] # skill names whose schemas must load first # Dependencies requires: bins: [uv, docker] env: [TYPEDB_HOST, TYPEDB_PORT, TYPEDB_DATABASE] optional_env: [] # CLI operations operations: ingestion: - ingest - add-entity artifacts: - list-artifacts - show-artifact queries: - list-entities - show-entity updates: - add-note - tag - search-tag # TypeDB entity types defined in schema.tql entity_types: - DOMAIN-entity # replace with actual entity type name # Bundle metadata — used by make package-skill and make install-skill bundle: schema_check_type: DOMAIN-entity # first entity type in schema.tql zip_name: DOMAIN-v1.0.zip version: "1.0"skills/_template/template.py25 KB12794168f734upstream ↗
#!/usr/bin/env python3 """ [DOMAIN NAME] CLI - [Brief description]. This script handles INGESTION and QUERIES. Claude handles SENSEMAKING via the SKILL.md. Usage: python .claude/skills/DOMAIN/DOMAIN.py <command> [options] Commands: # Ingestion ingest Fetch content from URL and store as artifact add-entity Add an entity manually # Artifacts (for Claude's sensemaking) list-artifacts List artifacts by analysis status show-artifact Get artifact content for Claude to read # Queries list-entities List all entities show-entity Get entity details # Updates update-status Update entity status add-note Create a note about any entity tag Tag an entity search-tag Search by tag Environment: TYPEDB_HOST TypeDB server host (default: localhost) TYPEDB_PORT TypeDB server port (default: 1729) TYPEDB_DATABASE Database name (default: alhazen_notebook) ALHAZEN_CACHE_DIR File cache directory (default: ~/.alhazen/cache) """ import argparse import json import os import sys from pathlib import Path # Add src to path for imports sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src")) # Optional: for URL fetching try: import requests from bs4 import BeautifulSoup REQUESTS_AVAILABLE = True except ImportError: REQUESTS_AVAILABLE = False # TypeDB driver try: from typedb.driver import Credentials, DriverOptions, TransactionType, TypeDB TYPEDB_AVAILABLE = True except ImportError: TYPEDB_AVAILABLE = False print( "Warning: typedb-driver not installed. Install with: pip install 'typedb-driver>=3.0.0'", file=sys.stderr, ) try: from skillful_alhazen.utils.skill_helpers import ( escape_string, generate_id, get_timestamp, check_infrastructure, ) except ImportError: import uuid from datetime import datetime, timezone def escape_string(s: str) -> str: if s is None: return "" return s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "") def generate_id(prefix: str) -> str: return f"{prefix}-{uuid.uuid4().hex[:12]}" def get_timestamp() -> str: return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S") def check_infrastructure(*args, **kwargs): pass # no-op if pkg unavailable # Cache utilities for large artifacts try: from skillful_alhazen.utils.cache import ( save_to_cache, load_from_cache_text, should_cache, get_cache_stats, format_size, ) CACHE_AVAILABLE = True except ImportError: CACHE_AVAILABLE = False # Fallback: define minimal versions if cache module not available def should_cache(content): return False def get_cache_stats(): return {"error": "Cache module not available"} def format_size(size): return f"{size} bytes" # ============================================================================= # CONFIGURATION # ============================================================================= TYPEDB_HOST = os.getenv("TYPEDB_HOST", "localhost") TYPEDB_PORT = int(os.getenv("TYPEDB_PORT", "1729")) TYPEDB_DATABASE = os.getenv("TYPEDB_DATABASE", "alh_core") TYPEDB_USERNAME = os.getenv("TYPEDB_USERNAME", "admin") TYPEDB_PASSWORD = os.getenv("TYPEDB_PASSWORD", "password") # TODO: Update these constants for your domain DOMAIN_PREFIX = "domain" # e.g., "jobhunt", "scilit" ENTITY_TYPE = f"{DOMAIN_PREFIX}-entity" ARTIFACT_TYPE = f"{DOMAIN_PREFIX}-artifact" # ============================================================================= # UTILITIES # ============================================================================= def get_driver(): """Get TypeDB driver connection.""" return TypeDB.driver( f"{TYPEDB_HOST}:{TYPEDB_PORT}", Credentials(TYPEDB_USERNAME, TYPEDB_PASSWORD), DriverOptions(is_tls_enabled=False), ) def get_attr(entity: dict, attr_name: str, default=None): """Safely extract attribute value from a TypeDB 3.x fetch result dict.""" return entity.get(attr_name, default) def fetch_url_content(url: str) -> tuple[str, str]: """ Fetch URL and return (title, text_content). Returns basic parsed content - Claude will do the intelligent extraction. """ if not REQUESTS_AVAILABLE: return "", "" headers = {"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"} try: response = requests.get(url, headers=headers, timeout=30) response.raise_for_status() soup = BeautifulSoup(response.text, "html.parser") # Remove script and style elements for element in soup(["script", "style", "nav", "footer", "header"]): element.decompose() title = soup.title.string if soup.title else "" # Get text content text = soup.get_text(separator="\n", strip=True) # Clean up whitespace lines = [line.strip() for line in text.splitlines() if line.strip()] text = "\n".join(lines) # Limit content size if len(text) > 50000: text = text[:50000] + "\n... [truncated]" return title, text except Exception as e: print(f"Error fetching URL: {e}", file=sys.stderr) return "", "" # ============================================================================= # INGESTION COMMANDS # ============================================================================= def cmd_ingest(args): """ Fetch content from URL and store as artifact. This implements the INGESTION phase of the curation pattern: - Fetches URL content (raw, unedited) - Stores as artifact with provenance - Creates placeholder entity - Claude does the SENSEMAKING separately """ if not REQUESTS_AVAILABLE: print(json.dumps({"success": False, "error": "requests/beautifulsoup4 not installed"})) return url = args.url title, content = fetch_url_content(url) if not content: print(json.dumps({"success": False, "error": "Could not fetch URL content"})) return # Generate IDs entity_id = generate_id("entity") artifact_id = generate_id("artifact") timestamp = get_timestamp() placeholder_name = title if title else f"Content from {url[:50]}" with get_driver() as driver: # Create entity placeholder with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: entity_query = f'''insert $e isa {ENTITY_TYPE}, has id "{entity_id}", has name "{escape_string(placeholder_name)}", has created-at {timestamp};''' tx.query(entity_query).resolve() tx.commit() # Create artifact with content (inline or cached) with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: # Check if content should be cached externally (>50KB) if CACHE_AVAILABLE and should_cache(content): # Store in cache cache_result = save_to_cache( artifact_id=artifact_id, content=content, mime_type="text/html", ) artifact_query = f'''insert $a isa {ARTIFACT_TYPE}, has id "{artifact_id}", has name "Content: {escape_string(placeholder_name)}", has cache-path "{cache_result['cache_path']}", has mime-type "text/html", has file-size {cache_result['file_size']}, has content-hash "{cache_result['content_hash']}", has source-uri "{escape_string(url)}", has created-at {timestamp};''' else: # Store inline in TypeDB artifact_query = f'''insert $a isa {ARTIFACT_TYPE}, has id "{artifact_id}", has name "Content: {escape_string(placeholder_name)}", has content "{escape_string(content)}", has source-uri "{escape_string(url)}", has created-at {timestamp};''' tx.query(artifact_query).resolve() tx.commit() # Link artifact to entity with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: rep_query = f'''match $a isa {ARTIFACT_TYPE}, has id "{artifact_id}"; $e isa {ENTITY_TYPE}, has id "{entity_id}"; insert (artifact: $a, referent: $e) isa representation;''' tx.query(rep_query).resolve() tx.commit() # Add tags if specified if args.tags: for tag_name in args.tags: tag_id = generate_id("tag") with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: tag_check = f'match $t isa tag, has name "{tag_name}"; fetch {{ "id": $t.id }};' existing_tag = list(tx.query(tag_check).resolve()) if not existing_tag: with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query( f'insert $t isa tag, has id "{tag_id}", has name "{tag_name}";' ).resolve() tx.commit() with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query(f'''match $e isa {ENTITY_TYPE}, has id "{entity_id}"; $t isa tag, has name "{tag_name}"; insert (tagged-entity: $e, tag: $t) isa tagging;''').resolve() tx.commit() print( json.dumps( { "success": True, "entity_id": entity_id, "artifact_id": artifact_id, "url": url, "content_length": len(content), "status": "raw", "message": "Content ingested. Artifact stored - ask Claude to 'analyze this' for sensemaking.", }, indent=2, ) ) def cmd_add_entity(args): """Add an entity manually.""" entity_id = args.id or generate_id("entity") timestamp = get_timestamp() query = f'''insert $e isa {ENTITY_TYPE}, has id "{entity_id}", has name "{escape_string(args.name)}", has created-at {timestamp}''' if args.description: query += f', has description "{escape_string(args.description)}"' query += ";" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query(query).resolve() tx.commit() print(json.dumps({"success": True, "entity_id": entity_id, "name": args.name})) # ============================================================================= # ARTIFACT COMMANDS # ============================================================================= def cmd_list_artifacts(args): """List artifacts, optionally filtered by analysis status.""" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: query = f"""match $a isa {ARTIFACT_TYPE}; fetch {{ "id": $a.id, "name": $a.name, "source-uri": $a.source-uri, "created-at": $a.created-at }};""" artifacts = list(tx.query(query).resolve()) results = [] for art in artifacts: artifact_id = art.get("id") # Check for notes (simple heuristic for "analyzed") notes_query = f'''match $a isa {ARTIFACT_TYPE}, has id "{artifact_id}"; (artifact: $a, referent: $e) isa representation; (note: $n, subject: $e) isa aboutness; fetch {{ "id": $n.id }};''' try: notes = list(tx.query(notes_query).resolve()) has_notes = len(notes) > 0 except Exception: has_notes = False status = "analyzed" if has_notes else "raw" if args.status and args.status != "all": if args.status != status: continue results.append( { "id": artifact_id, "name": art.get("name"), "source_url": art.get("source-uri"), "created_at": art.get("created-at"), "status": status, } ) print( json.dumps( { "success": True, "artifacts": results, "count": len(results), "filter": args.status or "all", }, indent=2, ) ) def cmd_show_artifact(args): """Get artifact content for Claude to read during sensemaking.""" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: # Include cache attributes in fetch query = f'''match $a isa {ARTIFACT_TYPE}, has id "{args.id}"; fetch {{ "id": $a.id, "name": $a.name, "content": $a.content, "cache-path": $a.cache-path, "mime-type": $a.mime-type, "file-size": $a.file-size, "source-uri": $a.source-uri, "created-at": $a.created-at }};''' result = list(tx.query(query).resolve()) if not result: print(json.dumps({"success": False, "error": "Artifact not found"})) return # Get linked entity entity_query = f'''match $a isa {ARTIFACT_TYPE}, has id "{args.id}"; (artifact: $a, referent: $e) isa representation; fetch {{ "id": $e.id, "name": $e.name }};''' entity_result = list(tx.query(entity_query).resolve()) art = result[0] # Get content - either from inline content or from cache cache_path = art.get("cache-path") if cache_path and CACHE_AVAILABLE: # Load from cache try: content = load_from_cache_text(cache_path) storage = "cache" except FileNotFoundError: content = f"[ERROR: Cache file not found: {cache_path}]" storage = "cache_missing" else: # Get inline content content = art.get("content") storage = "inline" output = { "success": True, "artifact": { "id": art.get("id"), "name": art.get("name"), "source_url": art.get("source-uri"), "created_at": art.get("created-at"), "content": content, "storage": storage, "cache_path": cache_path, "mime_type": art.get("mime-type"), "file_size": art.get("file-size"), }, "entity": None, } if entity_result: ent = entity_result[0] output["entity"] = { "id": ent.get("id"), "name": ent.get("name"), } print(json.dumps(output, indent=2)) # ============================================================================= # QUERY COMMANDS # ============================================================================= def cmd_list_entities(args): """List all entities.""" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: query = f"""match $e isa {ENTITY_TYPE}; fetch {{ "id": $e.id, "name": $e.name, "created-at": $e.created-at }};""" results = list(tx.query(query).resolve()) entities = [] for r in results: entities.append( { "id": r.get("id"), "name": r.get("name"), "created_at": r.get("created-at"), } ) print(json.dumps({"success": True, "entities": entities, "count": len(entities)}, indent=2)) def cmd_show_entity(args): """Get entity details.""" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: query = f'''match $e isa {ENTITY_TYPE}, has id "{args.id}"; fetch {{ "id": $e.id, "name": $e.name, "description": $e.description, "created-at": $e.created-at }};''' result = list(tx.query(query).resolve()) if not result: print(json.dumps({"success": False, "error": "Entity not found"})) return # Get notes notes_query = f'''match $e isa {ENTITY_TYPE}, has id "{args.id}"; (note: $n, subject: $e) isa aboutness; fetch {{ "id": $n.id, "name": $n.name, "content": $n.content }};''' notes_result = list(tx.query(notes_query).resolve()) # Get tags tags_query = f'''match $e isa {ENTITY_TYPE}, has id "{args.id}"; (tagged-entity: $e, tag: $t) isa tagging; fetch {{ "name": $t.name }};''' tags_result = list(tx.query(tags_query).resolve()) output = { "success": True, "entity": result[0], "notes": notes_result, "tags": [t.get("name") for t in tags_result], } print(json.dumps(output, indent=2, default=str)) # ============================================================================= # UPDATE COMMANDS # ============================================================================= def cmd_add_note(args): """Create a note about an entity.""" note_id = args.id or generate_id("note") timestamp = get_timestamp() query = f'''insert $n isa note, has id "{note_id}", has content "{escape_string(args.content)}", has created-at {timestamp}''' if args.name: query += f', has name "{escape_string(args.name)}"' if args.confidence: query += f", has confidence {args.confidence}" query += ";" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query(query).resolve() tx.commit() with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: about_query = f'''match $n isa note, has id "{note_id}"; $s isa entity, has id "{args.about}"; insert (note: $n, subject: $s) isa aboutness;''' tx.query(about_query).resolve() tx.commit() if args.tags: for tag_name in args.tags: tag_id = generate_id("tag") with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: tag_check = f'match $t isa tag, has name "{tag_name}"; fetch {{ "id": $t.id }};' existing_tag = list(tx.query(tag_check).resolve()) if not existing_tag: with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query( f'insert $t isa tag, has id "{tag_id}", has name "{tag_name}";' ).resolve() tx.commit() with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query(f'''match $n isa note, has id "{note_id}"; $t isa tag, has name "{tag_name}"; insert (tagged-entity: $n, tag: $t) isa tagging;''').resolve() tx.commit() print(json.dumps({"success": True, "note_id": note_id, "about": args.about})) def cmd_tag(args): """Tag an entity.""" with get_driver() as driver: tag_id = generate_id("tag") with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: tag_check = f'match $t isa tag, has name "{args.tag}"; fetch {{ "id": $t.id }};' existing_tag = list(tx.query(tag_check).resolve()) if not existing_tag: with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query(f'insert $t isa tag, has id "{tag_id}", has name "{args.tag}";').resolve() tx.commit() with driver.transaction(TYPEDB_DATABASE, TransactionType.WRITE) as tx: tx.query(f'''match $e isa entity, has id "{args.entity}"; $t isa tag, has name "{args.tag}"; insert (tagged-entity: $e, tag: $t) isa tagging;''').resolve() tx.commit() print(json.dumps({"success": True, "entity": args.entity, "tag": args.tag})) def cmd_search_tag(args): """Search entities by tag.""" with get_driver() as driver: with driver.transaction(TYPEDB_DATABASE, TransactionType.READ) as tx: query = f'''match $t isa tag, has name "{args.tag}"; (tagged-entity: $e, tag: $t) isa tagging; fetch {{ "id": $e.id, "name": $e.name }};''' results = list(tx.query(query).resolve()) print( json.dumps( { "success": True, "tag": args.tag, "entities": results, "count": len(results), }, indent=2, default=str, ) ) # ============================================================================= # MAIN # ============================================================================= def main(): # Infrastructure check — fast-fails with helpful message if TypeDB/dashboard missing check_infrastructure( skill_name="DOMAIN", # replace with actual skill name schema_check_type="DOMAIN-main-entity", # replace: first entity in schema.tql has_dashboard=False, # set True if skill has dashboard/ zip_name="domain-v1.0.zip", # replace: from skill.yaml bundle.zip_name ) parser = argparse.ArgumentParser( description="[DOMAIN] CLI - [Brief description]" ) subparsers = parser.add_subparsers(dest="command", help="Command to run") # ingest p = subparsers.add_parser("ingest", help="Fetch content from URL and store as artifact") p.add_argument("--url", required=True, help="Source URL") p.add_argument("--tags", nargs="+", help="Tags to apply") # add-entity p = subparsers.add_parser("add-entity", help="Add an entity manually") p.add_argument("--name", required=True, help="Entity name") p.add_argument("--description", help="Description") p.add_argument("--id", help="Specific ID") # list-artifacts p = subparsers.add_parser("list-artifacts", help="List artifacts by status") p.add_argument( "--status", choices=["raw", "analyzed", "all"], help="Filter: raw, analyzed, or all", ) # show-artifact p = subparsers.add_parser("show-artifact", help="Get artifact content") p.add_argument("--id", required=True, help="Artifact ID") # list-entities subparsers.add_parser("list-entities", help="List all entities") # show-entity p = subparsers.add_parser("show-entity", help="Get entity details") p.add_argument("--id", required=True, help="Entity ID") # add-note p = subparsers.add_parser("add-note", help="Create a note") p.add_argument("--about", required=True, help="Entity ID this note is about") p.add_argument("--content", required=True, help="Note content") p.add_argument("--name", help="Note title") p.add_argument("--confidence", type=float, help="Confidence score (0.0-1.0)") p.add_argument("--tags", nargs="+", help="Tags to apply") p.add_argument("--id", help="Specific ID") # tag p = subparsers.add_parser("tag", help="Tag an entity") p.add_argument("--entity", required=True, help="Entity ID") p.add_argument("--tag", required=True, help="Tag name") # search-tag p = subparsers.add_parser("search-tag", help="Search by tag") p.add_argument("--tag", required=True, help="Tag to search for") args = parser.parse_args() if not TYPEDB_AVAILABLE: print(json.dumps({"success": False, "error": "typedb-driver not installed"})) sys.exit(1) if not args.command: parser.print_help() sys.exit(1) commands = { "ingest": cmd_ingest, "add-entity": cmd_add_entity, "list-artifacts": cmd_list_artifacts, "show-artifact": cmd_show_artifact, "list-entities": cmd_list_entities, "show-entity": cmd_show_entity, "add-note": cmd_add_note, "tag": cmd_tag, "search-tag": cmd_search_tag, } try: commands[args.command](args) except Exception as e: print(json.dumps({"success": False, "error": str(e)})) import traceback traceback.print_exc(file=sys.stderr) sys.exit(1) if __name__ == "__main__": main()skills/_template/USAGE.md8.4 KBe937b86449b8upstream ↗
# Your Domain Name — Usage Reference ## Web Interface <!-- Optional: remove this section if this skill has no dashboard --> A Next.js dashboard is available at `http://localhost:3000/<your-domain>` when running `make dashboard-dev`. **Start the dashboard:** ```bash make dashboard-dev # starts on http://localhost:3000 ``` **Views:** - **[View Name]** (`/<your-domain>`) — Description of the main view - **[Item Detail]** (`/<your-domain>/item/{id}`) — Full detail page for a single item **Internal organization** (for contributors): - Pages: `dashboard/src/app/(<your-domain>)/<your-domain>/` - Components: `dashboard/src/components/<your-domain>/` - API routes: `dashboard/src/app/api/<your-domain>/` - TypeScript wrapper: `dashboard/src/lib/<your-domain>.ts` --- ## Ingestion Commands ### Ingest from URL **Triggers:** "add [item]", "ingest", "fetch", "new [item]" ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py ingest \ --url "https://example.com/item" \ --tags "tag1" "tag2" ``` **Options:** - `--url` (required): Source URL - `--tags`: Space-separated tags **Returns:** ```json { "success": true, "artifact_id": "artifact-abc123", "entity_id": "entity-xyz789", "status": "raw", "message": "Artifact stored - ask Claude to 'analyze this' for sensemaking." } ``` ### Add Entity Manually ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py add-entity \ --name "Entity Name" \ --description "Description" ``` --- ## Sensemaking Workflow **When user says "analyze [entity]" or "make sense of [artifact]":** 1. **Get the artifact content** ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py show-artifact --id "artifact-xyz" ``` 2. **Read and comprehend the content** - Look for: [list key things to extract] - Identify: [list entities to create] - Note: [list observations to make] 3. **Create/update related entities** ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py add-entity \ --name "Extracted Entity" \ --description "..." ``` 4. **Create fragments for key pieces** ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py add-fragment \ --artifact "artifact-xyz" \ --content "Extracted piece" ``` 5. **Create analysis notes** ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py add-note \ --about "entity-xyz" \ --type "analysis" \ --content "Claude's interpretation and insights..." ``` 6. **Flag uncertainties** with "uncertain" tag 7. **Report findings to user** - Summary of what was found - Key insights - Suggested next steps --- ## Query Commands ### List Entities ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py list-entities uv run python .claude/skills/<your-domain>/<your-domain>.py list-entities --status "active" ``` ### Show Entity Details ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py show-entity --id "entity-xyz" ``` ### List Artifacts ```bash # Show artifacts needing analysis uv run python .claude/skills/<your-domain>/<your-domain>.py list-artifacts --status raw # Show all artifacts uv run python .claude/skills/<your-domain>/<your-domain>.py list-artifacts --status all ``` --- ## Update Commands ### Update Status ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py update-status \ --entity "entity-xyz" \ --status "active" ``` ### Add Note ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py add-note \ --about "entity-xyz" \ --type "research" \ --content "Note content here" ``` ### Tag Entity ```bash uv run python .claude/skills/<your-domain>/<your-domain>.py tag \ --entity "entity-xyz" \ --tag "important" ``` --- ## Data Model ### Entity Types | Type | Description | |------|-------------| | `<domain>-entity` | Primary thing you track | | `<domain>-artifact` | Raw captured content | | `<domain>-fragment` | Extracted piece | | `<domain>-note` | Claude's analysis | ### Attributes | Attribute | Type | Description | |-----------|------|-------------| | `attribute-1` | string | Description | | `attribute-2` | datetime | Description | ### Relations | Relation | Description | |----------|-------------| | `relation-1` | How entities connect | --- ## Command Reference | Command | Description | Key Args | |---------|-------------|----------| | `ingest` | Fetch and store raw content | `--url` | | `add-entity` | Create entity manually | `--name` | | `add-note` | Create a note | `--about`, `--type`, `--content` | | `list-entities` | List all entities | `--status` | | `show-entity` | Get entity details | `--id` | | `list-artifacts` | List artifacts | `--status` | | `show-artifact` | Get artifact content | `--id` | | `update-status` | Change entity status | `--entity`, `--status` | | `tag` | Tag an entity | `--entity`, `--tag` | | `search-tag` | Find by tag | `--tag` | --- ## Analysis Workflow The Analysis phase turns accumulated sensemaking notes into structured, versioned, re-runnable insights. All curation skills use the **LinkML -> Pydantic -> Hamilton** pattern: ### 1. Define your schema (LinkML) Copy `schema/eval_schema_template.yaml` and rename it for your domain. Fill in: - Your **dimension names** in `DimensionScores` (rename `dimension_a`, `dimension_b`, etc.) - Your **entity categories** in the `EntityCategory` enum - Add optional fields freely — they default to `None`, keeping old records valid ### 2. Implement Pydantic models Create `eval_models.py` next to your skill script. Mirror the LinkML schema as Pydantic v2: ```python from pydantic import BaseModel, Field, model_validator from typing import Annotated, Optional from enum import Enum Score = Annotated[int, Field(ge=0, le=3)] class DimensionScores(BaseModel): dimension_a: Score dimension_b: Score total: int = 0 @model_validator(mode="after") def compute_total(self) -> "DimensionScores": self.total = self.dimension_a + self.dimension_b return self class EntityAssessment(BaseModel): id: str name: str scores: DimensionScores assessment_summary: Optional[str] = None parse_warnings: list[str] = [] ``` Generate JSON Schema for documentation: ```bash uv run python eval_models.py > schema/<skill>_schema.json ``` ### 3. Write a Hamilton pipeline Copy `pipelines/pipeline_template.py` and adapt: - `fetch_records(investigation_id)` — TypeQL query for your entities + assessment notes - `parse_records(fetch_records)` — keyword matching on your dimension labels - `table_data()` — serialises to JSON (no changes needed) - `plot_code()` — replace the placeholder with your Observable Plot expression **The sensemaking agent must write structured score tables** in assessment notes using this format so the parser can extract scores: ```markdown | Criterion | Score (0-3) | Notes | |---|---|---| | Dimension A label | 2 | explanation | | Dimension B label | 1 | explanation | ``` ### 4. Register the pipeline in TypeDB ```bash uv run python .claude/skills/<skill>/<skill>.py add-pipeline \ --investigation <ID> \ --title "My Analysis" \ --analysis-type pipeline-plot \ --pipeline-script "@skills/<skill>/pipelines/pipeline_name.py" \ --pipeline-config '{"outputs":["plot_code","table_data"],"inputs":{"investigation_id":"<ID>"},"env_inputs":{}}' ``` ### 5. Run the pipeline ```bash uv run python .claude/skills/<skill>/<skill>.py run-pipeline --id <analysis-id> ``` Re-run any time new sensemaking notes are added — the pipeline reads from TypeDB and re-generates outputs. ### 6. View in dashboard Navigate to the Analysis tab of your investigation page. The heatmap renders immediately using the pre-computed `table_data` stored in TypeDB. ### Schema Evolution Adding new analysis dimensions later: 1. Add `Optional` field to LinkML YAML and Pydantic model (new field = no migration) 2. Re-run the pipeline — existing records get `None`/0 for the new field 3. Update the sensemaking prompt to score the new dimension in future notes --- ## TypeDB Reference When writing custom queries, consult: - **This Skill's Schema:** `local_skills/<your-domain>/schema.tql` - **Core Schema:** `local_resources/typedb/alhazen_notebook.tql` ### Common Pitfalls (TypeDB 3.x) - **Fetch syntax** — Use `fetch { "key": $var.attr };` (JSON-style, NOT `fetch $var: attr1;`) - **No sessions** — Use `driver.transaction(database, TransactionType.X)` directly - **Update = delete + insert** — Can't modify attributes in place
Plain-text copy, no login: /skill-bundles/sciknow-io-skillful-alhazen-skills-template.md