feat: simplify examples for clarity

Author: BinglanLi

examples/10_skills.py

@@ -7,64 +7,82 @@
 
 Skills directory convention:
   skills/
-    ontology-design/
+    skill-name/
       SKILL.md            # required: YAML frontmatter + markdown body
       references/         # optional: bundled reference documents
-        owl_spec.md
       scripts/            # optional: bundled template scripts
-        template.py
 
-Single agent: full skill body is always injected.
-Multiple skills: catalog mode (metadata only) shown initially;
-the retrieve node selects relevant skills per task and injects their full bodies.
+Single skill:  full body always injected into the system prompt.
+Multiple skills: catalog mode (name + description only) shown initially;
+  the retrieve node selects relevant skills per task and injects full bodies.
 """
 
-from BaseAgent import BaseAgent
+from BaseAgent import BaseAgent, Skill
 from BaseAgent.agent_spec import AgentSpec
 
 SKILLS_DIR = "examples/skills"
 
 # --------------------------
-# Single agent, all skills (legacy glob mode — no AgentSpec)
+# Single agent, single skill
 # --------------------------
-agent = BaseAgent(skills_directory=SKILLS_DIR)
-# All SKILL.md files under SKILLS_DIR are loaded.
-# With multiple skills, the system prompt shows a catalog; the retrieve node
-# selects relevant skill bodies on each run.
+# With one skill, the full body is always injected — no catalog mode.
+agent = BaseAgent()
+agent.add_skill(f"{SKILLS_DIR}/data-analyst/SKILL.md")
 
 # --------------------------
-# Single agent, ad-hoc skill from object
+# Ad-hoc skill from object
 # --------------------------
-from BaseAgent.resources import Skill
-
+# Build a Skill inline without a SKILL.md file.
 agent2 = BaseAgent()
 agent2.add_skill(Skill(
-    name="cypher-export",
-    description="Best practices for exporting data to Memgraph via Cypher",
-    tools=["run_python_repl"],
-    instructions="## Cypher Export\n1. Batch nodes in chunks of 1000\n2. Use MERGE to avoid duplicates",
+    name="citation-formatter",
+    description="Formats literature references in APA or Vancouver style",
+    tools=[],
+    instructions="## Citation rules\n1. Vancouver: number citations in order of appearance.\n2. APA: Author, Year, Title, Journal, DOI.",
 ))
 
 # --------------------------
-# Multi-agent setup (spec-driven targeted loading)
+# Multi-agent, glob mode (all skills)
+# --------------------------
+# load_skills() globs all SKILL.md files under SKILLS_DIR.
+# With 3 skills progressive disclosure applies: the system prompt initially
+# shows a catalog (name + description only); the retrieve node injects full
+# skill bodies relevant to each task.
+agent3 = BaseAgent(skills_directory=SKILLS_DIR)
+
+# --------------------------
+# Multi-agent, targeted loading
 # --------------------------
 # Each agent loads ONLY the skills it needs:
-#   spec.skill_names → loads {skills_directory}/{name}/SKILL.md directly (no glob)
+#   spec.skill_names → resolves {skills_directory}/{name}/SKILL.md directly.
+# Skill names must exactly match the subdirectory name under SKILLS_DIR.
 
-oncology_agent = BaseAgent(
+analyst_agent = BaseAgent(
     skills_directory=SKILLS_DIR,
     spec=AgentSpec(
-        name="oncology_agent",
-        role="A disease domain expert that defines disease ontology schemas",
-        skill_names=["oncology_agent_protocol"],
+        name="analyst-agent",
+        role="A data analyst that profiles and summarises tabular biomedical datasets",
+        skill_names=["data-analyst"],
     ),
 )
 
-mapping_agent = BaseAgent(
+mapper_agent = BaseAgent(
     skills_directory=SKILLS_DIR,
     spec=AgentSpec(
-        name="mapping_agent",
-        role="An ontology alignment agent that maps extracted data to OWL terms",
-        skill_names=["mapping_agent_protocol"],
+        name="mapper-agent",
+        role="An ontology alignment agent that maps tabular columns to OWL terms",
+        skill_names=["ontology-mapper"],
     ),
 )
+
+# --------------------------
+# Bundled resources
+# --------------------------
+# The ontology-mapper skill has a references/ subdirectory.
+# When any loaded skill has bundled resources, BaseAgent injects
+# read_skill_resource(skill_name, path) into the REPL namespace so the
+# agent can read those files at runtime:
+#
+#   content = read_skill_resource("ontology-mapper", "references/owl_primer.md")
+#
+# Path traversal outside the skill directory is blocked.

examples/skills/data-analyst/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: data-analyst
+description: Guides exploratory data analysis on tabular biomedical datasets using pandas and matplotlib
+tools:
+  - run_python_repl
+---
+
+## Your role
+You load, inspect, and summarize tabular datasets. You write clean, reproducible pandas code
+and produce charts that help the user understand their data before further processing.
+
+## Loading data
+1. Use `pd.read_csv()` or `pd.read_excel()` as appropriate.
+2. Print `df.shape`, `df.dtypes`, and `df.head()` to orient yourself.
+3. Check for missing values with `df.isnull().sum()`.
+
+## Summarising distributions
+- For numeric columns: `df.describe()` and a histogram via `df[col].hist()`.
+- For categorical columns: `df[col].value_counts(normalize=True)`.
+
+## Reporting findings
+Summarise every result in plain English immediately after each code block.
+End your analysis with a bullet-point summary of key observations.

examples/skills/database_agent_protocol/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: ontology-mapper
+description: Maps columns in processed tabular data to OWL ontology classes and properties
+tools:
+  - run_python_repl
+---
+
+## Your role
+You align tabular data to an OWL ontology by identifying the correct class for each
+entity and the correct data/object property for each column.
+
+## Mapping workflow
+1. Inspect the table: print column names, dtypes, and a sample row.
+2. Read `references/owl_primer.md` via `read_skill_resource("ontology-mapper", "references/owl_primer.md")`
+   to review available OWL classes and properties.
+3. For each column decide: entity identifier, label, data property, or relationship.
+4. Write the mapping as a Python dict and validate by checking that every
+   referenced class and property appears in the primer.
+
+## Mapping dict format
+```python
+mapping = {
+    "node_type": "Gene",           # OWL class name
+    "id_column": "entrez_id",      # column used as IRI
+    "label_column": "gene_symbol",
+    "data_property_map": {
+        "description": "skos:definition",
+        "chromosome": "faldo:location",
+    },
+}
+```
+
+## When a class or property is missing
+Note the gap in your response and ask the user whether to add it to the ontology
+or skip the column for now. Never invent OWL terms that are not in the primer.

examples/skills/mapping_agent_protocol/SKILL.md

@@ -0,0 +1,33 @@
+# OWL Primer: Biomedical Knowledge Graph Classes and Properties
+
+Reference document for the `ontology-mapper` skill.
+
+## Node classes
+
+| Class | Description |
+|---|---|
+| `Gene` | A genomic locus encoding a functional product |
+| `Protein` | A translated gene product |
+| `Disease` | A pathological condition with a defined clinical presentation |
+| `Drug` | A chemical compound used for therapeutic purposes |
+| `Pathway` | A defined sequence of molecular interactions |
+| `Phenotype` | An observable characteristic of an organism |
+
+## Data properties
+
+| Property | Domain | Range | Description |
+|---|---|---|---|
+| `skos:definition` | Any | `xsd:string` | Human-readable definition |
+| `skos:prefLabel` | Any | `xsd:string` | Preferred display label |
+| `schema:identifier` | Any | `xsd:string` | External database identifier |
+| `faldo:location` | Gene | `xsd:string` | Genomic coordinates |
+| `schema:molecularFormula` | Drug | `xsd:string` | Chemical formula |
+
+## Object properties (relationships)
+
+| Property | Domain | Range | Description |
+|---|---|---|---|
+| `ro:causes` | Disease | Phenotype | Disease causes a phenotype |
+| `ro:participates_in` | Protein | Pathway | Protein participates in a pathway |
+| `ro:has_target` | Drug | Protein | Drug targets a protein |
+| `ro:associated_with` | Gene | Disease | Gene is associated with disease |

examples/skills/memgraph_agent_protocol/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: report-writer
+description: Structures analytical findings into a clear, well-formatted written report
+tools: []
+---
+
+## Your role
+You turn raw analytical results into a concise, well-structured report suitable for
+a scientific audience. You do not re-run analyses — you interpret and present them.
+
+## Report structure
+Every report must include these sections in order:
+
+1. **Background** — one paragraph: what question was asked and why it matters.
+2. **Methods** — bullet list of data sources and processing steps used.
+3. **Results** — findings presented as numbered key points, each supported by a
+   specific number or observation from the analysis.
+4. **Limitations** — one paragraph on caveats the reader should keep in mind.
+5. **Next steps** — two or three concrete follow-up actions.
+
+## Style rules
+- Use active voice and present tense.
+- Spell out abbreviations on first use.
+- Every claim must reference a specific result; avoid vague qualifiers ("seems", "might").