shugyo-mcp
Skill1 starsChanged 8 months agoMITView on GitHub
Guide for querying company data through Shugyo's digital twin. Teaches a context-first workflow — build understanding of the company's ontology, processes, and metrics, then clarify ambiguity before writing SQL. Use when the user asks any question about their company data via the shugyo-ai MCP server.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- appunite-brandSkill
- communication-analystSkill
- meeting-memoSkill
- roam-transcript-syncSkill
- spec-interviewSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
If $ARGUMENTS is empty, ask the user what they want to know.
- Distinctive: line 37
Follow these phases in order.
- Very specific: line 41
Call get_approach to get the platform overview, data flow, and tool usage guide.
- Distinctive: line 45
Before touching any table, understand what the company tracks and how.
- Very specific: line 85
Only now write and run SQL via run_query.
- Very specific: line 87
Use the exact column names confirmed via get_table_schema
- Very specific: line 88
Follow any gotchas from get_table_context (e.g., date filters, null handling, deduplication)
- Distinctive: line 89
Prefer vetted SQL patterns from metric definitions or table context over ad-hoc queries
- Very specific: line 96
Use the company's terminology (from query_knowledge)
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Help the user answer a question about their company using Shugyo MCP tools: $ARGUMENTS
If $ARGUMENTS is empty, ask the user what they want to know.
The Problem You're Solving
Shugyo is a digital twin of the company — it models the business as an ontology of entities, processes, and metrics backed by real data in BigQuery. When users ask questions, the instinct is to jump straight to discovering tables and running SQL. This produces shallow answers that miss business context. Worse, user questions are often imprecise — they use ambiguous terms, omit timeframes, or conflate related concepts. Querying without first understanding the business model and clarifying the question leads to wrong answers delivered with false confidence.
The workflow below solves both problems: build context first, then use that context to sharpen the question before writing any SQL.
What Kinds of Questions This Covers
Shugyo models the entire company, so this covers any question about company data:
- Financial — revenue, costs, margins, burn rate, runway, invoices, payments
- People & HR — headcount, hiring, attrition, team composition, compensation
- Sales & pipeline — deals, conversion rates, pipeline value, win rates
- Operations — project delivery, utilization, capacity, timelines
- Clients & accounts — client health, retention, contract values, engagement
- Product & usage — feature adoption, active users, engagement metrics
- Cross-domain — correlations across areas (e.g., "does team size affect project margins?")
- Any company-defined KPI — whatever the company tracks in Shugyo
Workflow: Context First, Queries Second
Follow these phases in order. Do NOT skip to SQL.
Phase 1: Understand the Platform
Call get_approach to get the platform overview, data flow, and tool usage guide. This orients you on what Shugyo is and how the data pipeline works.
Phase 2: Build Business Context
Before touching any table, understand what the company tracks and how. Run these calls (parallelize where possible):
get_ontology— the business domain model. Shows entities (clients, employees, projects, etc.), their relationships, and which BigQuery tables back them. This is the map of the business.explore_processes_and_metrics— all business processes with their pre-built metrics. A metric may already answer the user's question with vetted SQL — check before writing your own.query_knowledgewith the user's question — company-specific terminology, definitions, and business rules. For example, "revenue" might mean something specific (recognized vs. invoiced, including or excluding certain client types).
Phase 3: Narrow Down
Based on what you learned in Phase 2:
- If a pre-built metric answers the question — use
get_metric_detailsto get its full definition including SQL, goal, unit, and category. You may be able to run this SQL directly or adapt it slightly. - If a process is relevant — use
get_process_detailsto see all its metrics and understand the full business workflow. - If you need to explore specific tables — now use
get_table_contextfor gotchas, anti-patterns, and vetted query examples. Thenget_table_schemafor exact column names and types. - If you need broader table discovery — use
discover_tablesfor the full catalog beyond the ontology. - If you need query best practices — use
get_docsfor SQL tips, data glossary, and troubleshooting.
Phase 4: Decompose & Clarify
Now you have business context. Before writing any SQL, use it to stress-test the user's question. Decompose the query and look for:
- Ambiguous terms — Does "revenue" mean recognized, invoiced, or contracted? Does "team" mean a department, a project team, or the whole company? Does "active" have a specific definition in
query_knowledge? - Missing scope — What time period? Which entity subset? (e.g., "our clients" — all clients, or only active ones?)
- Implicit assumptions — "How many people did we hire?" assumes a hiring process exists and has clean data. Does it?
- Logical gaps — A question like "what's our profit margin per project?" requires both revenue and cost data attributed to projects. Does the data model support that join?
- Metric mismatch — The user asks for X, but the closest pre-built metric measures Y. Are they the same thing, or is the difference meaningful?
If you find gaps or ambiguity, ask the user before proceeding. Frame the questions using what you learned — reference specific metrics, entities, or terminology from the ontology so the user can give precise answers. Keep it to 2-3 focused questions max; don't interrogate.
Example: User asks "what's our revenue?" — this is missing a time frame (this month? this quarter? YTD?), and "revenue" itself may have multiple definitions in the company (recognized vs. invoiced vs. contracted). After checking query_knowledge you might learn the company tracks "recognized revenue" and "invoiced revenue" separately. Ask: "Do you mean recognized or invoiced revenue, and for what time period?"
If the question is clear and unambiguous, skip straight to Phase 5. Not every question needs clarification — "how many employees do we have right now?" is probably fine as-is.
Phase 5: Query with Confidence
Only now write and run SQL via run_query. Your query should:
- Use the exact column names confirmed via
get_table_schema - Follow any gotchas from
get_table_context(e.g., date filters, null handling, deduplication) - Prefer vetted SQL patterns from metric definitions or table context over ad-hoc queries
- Respect the 100-row limit — aggregate or filter appropriately
Phase 6: Answer in Business Terms
Present the results using the business language you learned in Phase 2:
- Use the company's terminology (from
query_knowledge) - Reference the process or metric by name if one exists
- Explain what the numbers mean in context, not just raw values
- Flag any caveats (data freshness, known gaps, edge cases from table context)
Key Principles
- Metrics before custom SQL — a pre-built metric is vetted and trusted. Always check
explore_processes_and_metricsfirst. - Ontology before tables — the ontology tells you how the business models itself. A table name alone doesn't tell you what it means.
- Knowledge before assumptions — terms like "active client", "revenue", or "utilization" have company-specific definitions. Use
query_knowledgeto learn them. - Context before schema —
get_table_contextreveals gotchas thatget_table_schemaalone won't show (e.g., "filter out status='deleted'" or "use invoice_date not created_at for revenue timing"). - Show your reasoning — briefly tell the user what you found in the ontology/metrics/knowledge, so they can correct misunderstandings before you query.
Available Tools Reference
| Tool | Purpose | When to call |
get_approach | Platform overview & tool guide | Always first |
get_ontology | Business domain model & entity-table mappings | Phase 2 — understand the business |
explore_processes_and_metrics | All processes with metric summaries | Phase 2 — check for existing metrics |
query_knowledge | Company glossary & business rules | Phase 2 — learn terminology |
get_metric_details | Full metric definition with SQL | Phase 3 — when a metric matches |
get_process_details | Process with all its metrics | Phase 3 — when a process is relevant |
get_table_context | Gotchas, anti-patterns, vetted queries | Phase 3 — before writing SQL |
get_table_schema | Column names, types, nullability | Phase 3 — confirm schema |
discover_tables | Full table catalog | Phase 3 — when ontology isn't enough |
get_docs | Query tips, glossary, troubleshooting | Phase 3 — best practices |
run_query | Execute read-only SQL (max 100 rows) | Phase 5 — only after clarification |
Anti-Patterns to Avoid
- Jumping to
discover_tables+run_query— you'll miss business context and write naive queries - Ignoring pre-built metrics — the company already defined how to calculate things; don't reinvent
- Assuming column semantics from names —
amountcould be gross, net, or something else entirely - Skipping
query_knowledge— business terms are often ambiguous without company-specific definitions - Presenting raw numbers without context — always frame results using the business language you learned
- Querying ambiguous questions without clarifying — "what's our revenue?" has at least 3 interpretations; use what you learned from ontology/knowledge to ask the right follow-up
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

