dimcli

Other Community

Repo stars 49
License MIT
Author repo dimcli

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Query the Dimensions Analytics API using the dimcli CLI tool. Use when the user wants to search or retrieve data from Dimensions…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Workflow”, “Query Structure”, “Output Format”, “Flags”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name dimcli directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Workflow / Query Structure / Output Format” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Dimcli Skill

Query the Dimensions Analytics API via dimcli -q "..." and present results with clickable Dimensions URLs.

Workflow

Identify the source and intent from the user's request
Construct a valid DSL query — always include id so URLs can be built
Run: dimcli -q "<query>" -f json
Parse JSON and present a numbered list with title, key metadata, and Dimensions URL
Offer follow-ups: refine, export to CSV, fetch more records

If unsure about available fields, run dimcli -q "describe schema" first.

DSL grammar and URL patterns: See grammar.md and urls.md.

Query Structure

search <source> [for "<keywords>"] [where <filters>] return <source>[field1+field2+...] [limit N] [sort by <field>]

Always include id in return fields. Use [basics] for a standard field set.

Output Format

Present results as a numbered list:

1. **Title of the work** (2023)
   Journal: Nature | Cited by: 142
   https://app.dimensions.ai/details/publication/pub.1234567890

2. ...

Summarise after the list: total found, date range, notable patterns.

Flags

Flag	Use case
`-f json`	Default — structured data
`-f csv --nice`	Clean tabular export
`-f df`	Formatted terminal table
`-f df --html`	HTML table with hyperlinks

Advanced

Large results: API returns max 1000/call (50k with pagination). Suggest narrowing filters or using query_iterative() in Python.
Schema lookup: dimcli -q "describe schema"
Export: dimcli -q "..." -f csv --nice > results.csv

Subcommand: `profile <grid_id>`

Generate a full profile report for an organisation, given its GRID ID (format: grid.XX).

Workflow

Run all queries sequentially (never in parallel — concurrent calls cause session conflicts).

Step 1 — Fetch organisation metadata:

dimcli -q "search organizations where id = \"<grid_id>\" return organizations[acronym+city_name+country_code+country_name+dimensions_url+established+external_ids_fundref+hierarchy_details+id+isni_ids+latitude+linkout+longitude+name+organization_child_ids+organization_parent_ids+organization_related_ids+ror_ids+status+types+ultimate_parent_id+wikidata_ids+wikipedia_url]" -f json 2>/dev/null

Note: organizations[all] is not valid — always enumerate fields explicitly.

Step 2 — Count documents per source:

Run each query below sequentially. Extract _stats.total_count from the JSON.

# Publications
dimcli -q "search publications where research_orgs = \"<grid_id>\" return publications limit 1" -f json 2>/dev/null

# Grants
dimcli -q "search grants where research_orgs = \"<grid_id>\" return grants limit 1" -f json 2>/dev/null

# Datasets
dimcli -q "search datasets where research_orgs = \"<grid_id>\" return datasets limit 1" -f json 2>/dev/null

# Clinical Trials
dimcli -q "search clinical_trials where research_orgs = \"<grid_id>\" return clinical_trials limit 1" -f json 2>/dev/null

# Patents — NOTE: uses 'assignees', not 'research_orgs'
dimcli -q "search patents where assignees = \"<grid_id>\" return patents limit 1" -f json 2>/dev/null

# Reports
dimcli -q "search reprots where research_orgs = \"<grid_id>\" return reports limit 1" -f json 2>/dev/null

# Policy Documents — NOTE: uses 'publisher_org', not 'research_orgs'
dimcli -q "search policy_documents where publisher_org = \"<grid_id>\" return policy_documents limit 1" -f json 2>/dev/null

Each source uses a different field name to filter by organisation:

Source Filter field

publications, grants, datasets, clinical_trials research_orgs

patents assignees

policy_documents publisher_org

Step 2b — Count documents where org is a funder:

# Publications (as funder)
dimcli -q "search publications where funders = \"<grid_id>\" return publications limit 1" -f json 2>/dev/null

# Grants (as funder) — NOTE: uses 'funder_orgs', not 'funders'
dimcli -q "search grants where funder_orgs = \"<grid_id>\" return grants limit 1" -f json 2>/dev/null

# Datasets (as funder)
dimcli -q "search datasets where funders = \"<grid_id>\" return datasets limit 1" -f json 2>/dev/null

# Clinical Trials (as funder)
dimcli -q "search clinical_trials where funders = \"<grid_id>\" return clinical_trials limit 1" -f json 2>/dev/null

# Patents (as funder)
dimcli -q "search patents where funders = \"<grid_id>\" return patents limit 1" -f json 2>/dev/null

# Reports (as funder) — NOTE: uses 'funder_orgs', not 'funders'
dimcli -q "search reports where funder_orgs = \"<grid_id>\" return reports limit 1" -f json 2>/dev/null

Step 3 — Piping to Python:

Always redirect stderr with 2>/dev/null before piping to Python. The CLI prints "Reusing cached session." to stdout, which breaks JSON parsing if included.

dimcli -q "..." -f json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['_stats']['total_count'])"

Output Format

Print the profile as a markdown report:

# Organisation Profile: <Name> (<acronym>)

**GRID ID:** `<id>` | **Status:** <status> | **Type:** <types> | **Established:** <year>

## Location
- City: <city>, <country>
- Coordinates: <lat>, <lon>

## Links
- Website: <linkout>
- Wikipedia: <wikipedia_url>
- Dimensions: <dimensions_url>

## External Identifiers
- ROR: <ror_ids>
- ISNI: <isni_ids>
- Wikidata: <wikidata_ids>
- FundRef IDs: <external_ids_fundref>

## Hierarchy
- Ultimate parent: <ultimate_parent_id>
- Parent orgs: <organization_parent_ids>
- Child orgs: <organization_child_ids>
- Related orgs: <organization_related_ids>

## Document Counts (as Research Org)
| Source | Count | Dimensions URL |
|--------|------:|----------------|
| Publications | N | https://app.dimensions.ai/discover/publication?and_facet_research_org=<grid_id> |
| Grants | N | https://app.dimensions.ai/discover/grant?search_mode=content&or_facet_research_org=<grid_id> |
| Datasets | N | https://app.dimensions.ai/discover/dataset?and_facet_research_org=<grid_id> |
| Clinical Trials | N | https://app.dimensions.ai/discover/clinical_trial?and_facet_research_org=<grid_id> |
| Patents | N | https://app.dimensions.ai/discover/patent?and_facet_research_org=<grid_id> |
| Reports | N | https://app.dimensions.ai/discover/technical_report?and_facet_research_org=<grid_id> |
| Policy Documents | N | https://app.dimensions.ai/discover/policy_document?and_facet_research_org=<grid_id> |
| **Total** | **N** | |

## Document Counts (as Funder)
| Source | Count | Dimensions URL |
|--------|------:|----------------|
| Publications | N | https://app.dimensions.ai/discover/publication?or_facet_funder=<grid_id> |
| Grants | N | https://app.dimensions.ai/discover/grant?or_facet_funder=<grid_id> |
| Datasets | N | https://app.dimensions.ai/discover/data_set?or_facet_funder=<grid_id> |
| Clinical Trials | N | https://app.dimensions.ai/discover/clinical_trial?or_facet_funder=<grid_id> |
| Patents | N | https://app.dimensions.ai/discover/patent?or_facet_funder=<grid_id> |
| Reports | N | https://app.dimensions.ai/discover/technical_report?or_facet_funder=<grid_id> |
| **Total** | **N** | |

Export

If the user asks to export, save the report to <grid_id>_profile.md using the Write tool. Confirm the file path after saving.

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Other
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 94 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @digital-science · MIT
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Python
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview dimcli.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# Dimcli Skill

Query the Dimensions Analytics API via `dimcli -q "..."` and present results with clickable Dimensions URLs.

## Workflow

1. Identify the source and intent from the user's request
2. Construct a valid DSL query — always include `id` so URLs can be built
3. Run: `dimcli -q "<query>" -f json`
4. Parse JSON and present a numbered list with title, key metadata, and Dimensions URL
5. Offer follow-ups: refine, export to CSV, fetch more records

If unsure about available fields, run `dimcli -q "describe schema"` first.

**DSL grammar and URL patterns:** See [grammar.md](references/grammar.md) and [urls.md](references/urls.md).

## Query Structure

```
search <source> [for "<keywords>"] [where <filters>] return <source>[field1+field2+...] [limit N] [sort by <field>]
```

Always include `id` in return fields. Use `[basics]` for a standard field set.

## Output Format

Present results as a numbered list:

```
1. **Title of the work** (2023)
   Journal: Nature | Cited by: 142
   https://app.dimensions.ai/details/publication/pub.1234567890

2. ...
```

Summarise after the list: total found, date range, notable patterns.

## Flags

| Flag | Use case |
|------|----------|
| `-f json` | Default — structured data |
| `-f csv --nice` | Clean tabular export |
| `-f df` | Formatted terminal table |
| `-f df --html` | HTML table with hyperlinks |

## Advanced

- **Large results**: API returns max 1000/call (50k with pagination). Suggest narrowing filters or using `query_iterative()` in Python.
- **Schema lookup**: `dimcli -q "describe schema"`
- **Export**: `dimcli -q "..." -f csv --nice > results.csv`

---

## Subcommand: `profile <grid_id>`

Generate a full profile report for an organisation, given its GRID ID (format: `grid.XX`).

### Workflow

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> Workflow → Query Structure → Output Format → Flags → Advanced → Subcommand: profile <gridid>
terms    -> DSL grammar and URL patterns · Title of the work · Large results · Schema lookup · Export · sequentially · Step 1 — Fetch organisation metadata · not valid
files/cmd -> dimcli -q "..." · dimcli -q "<query>" -f json · dimcli -q "describe schema" · [basics] · -f json · -f csv --nice · -f df · -f df --html
body sha256 -> 6014a93f5ef5

Source	Filter field
publications, grants, datasets, clinical_trials	`research_orgs`
patents	`assignees`
policy_documents	`publisher_org`

Decide Fit First

Design Intent

How To Use It

Boundaries And Review

Dimcli Skill

Workflow

Query Structure

Output Format

Flags

Advanced

Subcommand: profile <grid_id>

Workflow

Output Format

Export

Discussion

Subcommand: `profile <grid_id>`