⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

your-domain-name

sciknow-io@sciknow-io⭐ 24 stars· last commit 4mo ago· 17 open issues

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.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 24 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// 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

FilePurpose
SKILL.mdTemplate for skill documentation (what Claude reads)
template.pyTemplate for CLI script (TypeDB operations)
schema.tqlTemplate for TypeDB schema (data model)

Quick Start

  1. Copy this directory:

    cp -r .claude/skills/_template .claude/skills/<your-domain>
    
  2. Rename the script:

    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:

    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:

    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 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

// REPO STATS

24 stars
17 open issues
Last commit: 4mo ago