> For the complete documentation index, see [llms.txt](https://docs.cosmik.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cosmik.network/semble-mcp/agent-skills-for-semble.md). # Agent Skills for Semble give your agent access to various skill that help it interact with the Semble MCP server. These skill can be found [here](https://github.com/cosmik-network/semble-claude-plugin/tree/main/skills), or listed below: ## Getting Started ``` --- name: semble-getting-started description: Orientation for working with Semble — the core concepts (cards, collections, connections, libraries), how the MCP tools map to them, and the conventions Claude should follow. Activate at the start of any Semble task, or when the user asks what Semble is or what they can do with it. --- # Working with Semble Semble is a network for saving, connecting, and discovering URLs — built on the AT Protocol. Think of it as a shared, typed knowledge graph layered over the web. This skill orients you before you act; the `semble-deep-research` and `semble-activity-digest` skills cover specific workflows. ## Core concepts - **Card** — the atomic unit. A **URL card** represents a saved link; a **note card** is a markdown note attached to a URL. Cards have IDs. A URL can be saved by many users, each as their own card. - **Library** — a user's personal set of saved cards. "Saving" a URL adds a card to _your_ library. - **Collection** — a named, ordered group of URL cards. `OPEN` collections let others contribute; `CLOSED` ones don't. - **Connection** — a _typed, directional_ relationship between two things (URLs or cards): `SUPPORTS`, `OPPOSES`, `ADDRESSES`, `HELPFUL`, `LEADS_TO`, `RELATED`, `SUPPLEMENT`, `EXPLAINER`. This is the discourse-graph layer. Read `semble://connection-types` for exact semantics before asserting a specific type. - **Follow vs. Subscribe** — _following_ a user or collection drives your following-feed. _Subscribing_ drives notifications, at `CARD` / `CONNECTION` / `COLLECTION_SAVED` granularity. A subscription is an enhancement to a follow (must follow a user before subscribing to them). ## Identifiers - Users are addressed by **handle or DID** (the `identifier` param). - Cards, collections, and connections are addressed by **ID**. - Collections can also be addressed by **handle + record key** (their AT URI) via `get_collection_by_aturi`. - Many read tools accept either a **URL** or an ID — check each tool's schema. ## Tool map (what to reach for) **Read a single thing** - A URL you have in mind → `get_url_metadata` (add `includeStats: true`), then `get_card_network_context` for the full picture (savers, collections, notes, connections in one call). - A specific card / collection → `get_card`, `get_collection`. - A person → `get_account_profile` (others) or `get_my_profile` (self). **Search / discover** - Your own library → `search_library`. The whole network by keyword → `search_network`. - Conceptual / natural-language → `semantic_search`. "More like this URL" → `find_similar_urls`. - Collections → `search_collections`. People → `search_accounts`. - Recent activity → `get_global_feed`, `get_following_feed`. **Write (always confirm intent first — see below)** - Save a URL → `save_card` (can attach a note + add to collections in one call). - Relate two things → `connect_cards`. - Collections → `create_collection`, `update_collection`, add/remove cards via `update_card_associations`. - Social → `follow` / `subscribe` (and their inverses). ## Conventions to follow 1. **Confirm before writing.** Any create/update/delete (`save_card`, `connect_cards`, `create_collection`, `delete_*`, `follow`, `subscribe`, mark-read) changes the user's account. State exactly what you're about to do and get a clear go-ahead unless the user already gave an explicit, specific instruction. Treat every `delete_*` and `remove` tool as destructive and irreversible. 2. **Orient before you save.** Before saving a URL, it's usually worth a `get_library_status` (do they already have it?) and a quick `get_url_metadata`/`get_card_network_context` so you can save it into the right collections and reference existing notes/connections. 3. **Paginate deliberately.** List/search tools default to `limit: 10`, `page: 1`. Raise the limit or page through when the user wants breadth — don't silently stop at the first page and imply it's complete. Say when there's more. 4. **Prefer coarse tools for overviews.** When the user wants "the whole picture" of a URL, one `get_card_network_context` beats five separate calls. 5. **Attribute discovery with `viaCardId`.** When you save a URL you found _through_ another card, pass `viaCardId` — it credits the source and drives their notifications. 6. **Suggesting actions is your job, not a tool's.** After gathering data, reason over it and propose concrete next steps (follow this curator, connect these two papers as `SUPPORTS`, add this to that collection). There is no "suggest" tool — the suggestions come from you, and every proposed write still needs confirmation. ``` ## Activity Digest ``` --- name: semble-activity-digest description: Summarize what's happening on Semble — synthesize the global and following feeds, notifications, and recent collection activity into a digest, then suggest concrete follow-up actions (connections to make, people to follow, cards to save). Activate when the user asks "what's happening on Semble", "catch me up", "any updates", "what did I miss", or wants a digest of their feeds and notifications. --- # Semble Activity Digest Turn raw feed and notification data into a concise, useful digest plus suggested actions. Read `semble-getting-started` first if you haven't. Decide scope from the user's ask — a quick "anything new?" is lighter than a "catch me up on the week". ## Gather Pull from the relevant sources in parallel where you can: 1. **Notifications** — `get_unread_notification_count` first (cheap; tells you if there's anything). Then `get_notifications` (use `unreadOnly: true` for "what's new"). Types include `USER_ADDED_YOUR_CARD`, `SUBSCRIBED_USER_ADDED_CARD`, `USER_FOLLOWED_YOU`. These are the most personal and usually lead the digest. 2. **Following feed** — `get_following_feed`: activity from people the user follows. Activities are `CARD_COLLECTED` or `CONNECTION_CREATED`. This is the signal-rich feed. 3. **Global feed** — `get_global_feed`: broader network activity, for discovery beyond their circle. Include a modest slice; don't let it drown the personal items. Filter by `urlType` or `source` if the user has a focus. 4. **Optional deeper context** — if a collection or URL keeps recurring in the feeds, pull `get_collection` or `get_card_network_context` to explain _why_ it's active. Page back far enough to cover the window the user asked about (use `beforeActivityId` as a cursor for feeds). If you cap the window, say so — don't imply completeness you didn't check. ## Synthesize Don't replay the raw list. Cluster and interpret: - **Lead with the personal** — notifications that need or reward a response (someone saved your card, followed you, a subscribed user posted). - **Group by theme, not by timestamp** — "three people in your network engaged with AI-safety papers", "your collection _X_ got two new contributions" reads better than a reverse-chronological dump. - **Surface convergence** — the same URL, collection, or person recurring across feeds is the story. Call it out. - **Note who's active** — curators (in-network or not) who are producing good material right now. - **Keep it scannable** — short sections, concrete names and IDs, no filler. Length should match how much actually happened. ## Suggested actions Close with specific, grouped, ready-on-confirmation suggestions drawn from the digest: - **Respond** — reciprocate a follow, thank/subscribe to someone who added your card, mark notifications read (`mark_notifications_read` / `mark_all_notifications_read`). - **Connect** — the highest-value move: when the feed shows two related items (e.g. a new card that `SUPPORTS` or `OPPOSES` something the user already has), propose the typed connection with direction and type stated. - **Save** — feed URLs worth adding to the user's library; suggest the collection, check `get_library_status` first, and pass `viaCardId` for attribution to where you saw it. - **Follow / Subscribe** — recurring active curators or lively collections worth tracking; make the follow-vs-subscribe call for them. State each action concretely enough to execute, but don't execute — confirm first. The digest is the read; the actions are the offer. ``` ## Deep Research ``` --- name: semble-deep-research description: Multi-step research over the Semble network — run several complementary searches, crawl mutual collections and typed connections, evaluate results, track curators and collections worth following, and end with concrete suggested actions. Activate when the user asks to research, deeply explore, or map a topic in Semble, or wants to know "what's on Semble about X" beyond a single lookup. --- # Deep Research on Semble A single search rarely answers a real research question. This skill is a strategy for iterative, judgment-driven exploration of the Semble graph — _you_ decide the depth and branching per query; the steps below are a default, not a script to run blindly. Read `semble-getting-started` first if you haven't. ## The loop Work in rounds. After each round, decide whether you have enough or should branch further. ### 1. Cast a wide first net Run **complementary** searches, not one — they surface different things: - `search_network` (keyword) — exact-term matches across everyone's cards. - `semantic_search` (natural language) — conceptually related content the keywords miss. Start with a low/no `threshold`; tighten only if results are noisy. - `search_collections` — someone may have already curated this topic. A strong collection is often the best single find. - `search_accounts` — is there a person who _is_ the topic? Their library and connections become seeds. Dedupe across these by URL/card ID. Note the overlap — a URL surfaced by several searches is a strong signal. ### 2. Deepen on the strongest hits For the most promising URLs, get the full picture with `get_card_network_context` (metadata + stats + savers + collections + notes + connections in one call). From each, extract branch points: - **Connections** → follow typed edges with `get_url_connections`. An `EXPLAINER` or `SUPPORTS` edge points to the next thing worth reading. Respect direction (`forward`/`backward`/`both`). - **Collections** → open promising ones with `get_collection`; a good collection yields a whole cluster of vetted cards at once. - **Savers & note-writers** → the people repeatedly appearing around good content are curators worth tracking. - **Similarity** → `find_similar_urls` on a keystone URL to pull in semantically adjacent material the graph doesn't yet link. ### 3. Crawl mutuals and clusters Look for **convergence**, the highest-value signal in a graph: - URLs that appear across multiple good collections. - Users who both saved the keystone URLs _and_ curate relevant collections (`list_user_collections`, `list_contributed_collections`). - Dense connection neighborhoods — a URL with many typed edges is a hub. Expand a round or two along these, then stop. Don't crawl exhaustively; crawl toward convergence. ### 4. Evaluate, don't just collect As you go, judge results rather than dumping them: - **Relevance** — does it actually address the question, or just share keywords? - **Authority** — how many libraries saved it? Is it in curated collections? Do notes engage substantively? - **Role in the graph** — is it a hub, a leaf, a contrarian (`OPPOSES` edges)? Contrarian nodes are often the most useful. Drop weak hits early so later rounds don't inherit noise. ## Track as you go Keep a running tally across rounds (in your reasoning, surfaced in the final report): - **Key findings** — the URLs/cards that actually answer the question, with why each matters and its evidence (save count, collections, notes). - **Curators to follow/subscribe** — people who repeatedly surface good material. Note _why_ and whether follow (feed) or subscribe (notifications) fits. - **Collections to follow** — curated clusters worth ongoing attention. - **Open threads** — promising branches you didn't fully chase, so the user can direct a next round. ## Deliver: findings + suggested actions End every research session with two parts. **1. Synthesis.** A structured summary of what the network holds on the topic — the key findings, how they relate (agree/oppose/build-on), where the clusters and gaps are. Cite cards/collections/users by name and ID so the user (and you) can act on them. **2. Suggested actions.** Concrete, specific, and grouped — each ready to execute _on confirmation_: - **Save** — URLs found that aren't in the user's library yet (check with `get_library_status`); suggest which collection each belongs in, and pass `viaCardId` for attribution. - **Connect** — typed connections the research revealed but that don't exist yet ("paper A `SUPPORTS` paper B", "this post `OPPOSES` that one"). Propose the type and direction explicitly. - **Collect** — a new collection to hold the cluster you found, or existing cards to add to one. - **Contribute** if any open collections were discovered along the way, suggest to the user that they contribute relevant URLs to them (this is the same as adding a card to a collection, just that the collection is someone else's). - **Follow / Subscribe** — the curators and collections from your tally, with the follow-vs-subscribe choice made for them (does the user want to be notified about activity or just have it show up in a following feed?). Never execute writes as part of research. Gather, synthesize, propose — then let the user pick. This division is deliberate: the traversal and the judgment are yours; the commitment is theirs. ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cosmik.network/semble-mcp/agent-skills-for-semble.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.