{"id":"47ea9f8c-6c0a-4b95-8302-ab33386af0f7","slug":"scout-compass","kind":"skill","name":"Scout-Compass","summary":"Scout Compass — navigate from idea to installed skill with a smooth build, preview, and install flow.","owner":"JeremyGracey-AI","repoUrl":"https://github.com/JeremyGracey-AI/Scout-Compass","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-06-13T07:07:54.000Z","addedAt":"2026-10-21T11:05:06.907Z","logoUrl":"https://avatars.githubusercontent.com/u/231318344?u=e4524d37171216cd099f5b0bffc1e0ac96875272&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":["cli","flask","python","skill-generator"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T22:42:07.822Z","sample":false,"url":"https://conduits.dev/tools/scout-compass","language":"Python","transports":["stdio"],"install":{"pypi":"scout-compass"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Scout Compass\n\n> Navigate from idea to installed skill with a smooth build, preview, and install flow.\n\n> **Note:** The Agents League @ AI Skills Fest 2026 hackathon entry is\n> **[scout-compass-mcp](https://github.com/JeremyGracey-AI/scout-compass-mcp)**\n> (governed agent memory — the run-time half of the lifecycle). This repository\n> is the companion skill-authoring tool.\n\nA toolkit for authoring **Microsoft Scout** `SKILL.md` files tuned to senior Microsoft executives.\n\nIt ships three ways to create skills:\n\n1. **Python CLI** (`cli/compass.py`) — interactive or scriptable; writes directly into `~/.copilot/skills/`.\n2. **Web app** (`web/app.py`) — a persona-builder UI for non-technical users: fill a form (no YAML), preview the skills + automations, then one-click install into the Scout skills folder (or download a `.zip`). See [Web app](#web-app).\n3. **Meta-skill** (`meta_skill/compass/SKILL.md`) — drop this into Scout itself so Scout can author new exec skills on demand.\n\nAll three share the same eight executive workflow archetypes:\n\n| Archetype | What the resulting skill produces |\n|-----------|-----------------------------------|\n| `briefing` | One-page exec brief with KPI table, partner-org list, talking points |\n| `comms` | Audience-mode draft (team / partner-org / CVP / external / quick-reply / all-hands) with 3 subject lines and risk flags |\n| `triage` | Daily or weekly digest: top-of-mind (≤5), compliance flags, KPI exceptions, calendar table, delegations |\n| `strategy` | 2–4 page memo with recommendation, options table, sequencing, open questions |\n| `meeting-prep` | Run-of-show pack for a specific meeting: objective, time-boxed agenda, attendees + decision power, decisions to land, talking points |\n| `decisions-log` | Durable decision record: the call, options weighed, owner/approver, compliance + KPI tie, follow-ups, review date |\n| `one-on-one` | 1:1 prep card: since-last-time, follow-ups owed both ways, decisions to align, one earned growth/recognition note |\n| `review-prep` | MBR/QBR pack: KPI scorecard vs. target, narrative, wins, risks with recovery owners, asks for the room |\n\n## Seeded persona\n\nThe repo ships with one persona — **Morgan Reyes**, General Manager, Operations Enablement (Contoso Ltd.) — a fully fictional executive created for demos and tests. Charter, process domains, partner orgs, signature phrasing, and decision filters are all defined in `personas/morgan_reyes.yaml`.\n\nAdd more personas by dropping new YAML files into `personas/` matching the same shape.\n\n## Quickstart\n\n```bash\npip install pyyaml jinja2 flask\n\n# CLI — generate the four core skills for Morgan\npython cli/compass.py \\\n  --persona personas/morgan_reyes.yaml \\\n  --workflows briefing,comms,triage,strategy \\\n  --out ~/.copilot/skills \\\n  --prefix morgan\n\n# CLI — interactive mode\npython cli/compass.py\n\n# Web UI\npython web/app.py\n# open http://127.0.0.1:5000\n```\n\n## Installing the generated skills into Scout\n\nScout discovers custom skills automatically. Just place each skill folder in one of these directories\n([Microsoft docs](https://learn.microsoft.com/en-us/microsoft-scout/use-microsoft-scout#create-a-custom-skill)):\n\n| Tier | Path | When to use |\n|------|------|-------------|\n| Global user | `~/.copilot/skills/<slug>/SKILL.md` | This machine, all conversations |\n| Workspace (synced) | `~/.copilot/m-skills/<slug>/SKILL.md` | Synced across your devices |\n\nNo restart needed — Scout picks them up at the start of the next conversation.\n\n## Installing the meta-skill\n\n```bash\ncp -r meta_skill/compass ~/.copilot/skills/\n```\n\nThen ask Scout: *\"Make a new comms skill for Morgan Reyes — they need help drafting board-up updates on the partner lifecycle KPIs.\"* The meta-skill walks Scout through gathering the right persona inputs and renders a polished `SKILL.md`.\n\n## Repo layout\n\n```\nscout-compass/\n├── cli/\n│   └── compass.py              # generator + validator + interactive CLI\n├── web/\n│   ├── app.py                  # Flask app\n│   └── templates/index.html    # single-page UI\n├── meta_skill/\n│   └── compass/\n│       └── SKILL.md            # the skill that teaches Scout to author exec skills\n├── personas/\n│   └── morgan_reyes.yaml       # seed persona (fictional)\n├── templates/\n│   ├── briefing.md.j2          # Jinja2 templates — one per archetype\n│   ├── comms.md.j2\n│   ├── triage.md.j2\n│   ├── strategy.md.j2\n│   ├── meeting-prep.md.j2\n│   ├── decisions-log.md.j2\n│   ├── one-on-one.md.j2\n│   └── review-prep.md.j2\n└── README.md\n```\n\nExample skills aren't checked in — generate them by running the CLI against the seeded persona (`personas/morgan_reyes.yaml`).\n\n## SKILL.md spec used here\n\nPer the [Microsoft Scout docs](https://learn.microsoft.com/en-us/microsoft-scout/use-microsoft-scout#create-a-custom-skill):\n\n- The **skill name is the folder name** (e.g. `morgan-briefing/`), lowercase-hyphen.\n- YAML frontmatter delimited by `---`. The **only required field is `description`** (what the skill does + when to use it). The generator also emits an explicit `name` for portability with the browser installer.\n- Markdown body with the skill instructions. Up to ~1 MB. Keep it lean — Scout loads the whole body when the skill activates.\n- Drop the folder into `~/.copilot/skills/<slug>/` (or `~/.copilot/m-skills/<slug>/` to sync across devices). Auto-discovered at the start of each conversation.\n\nThe generator's validator (`--validate <path>`) enforces these rules.\n\n## Design choices worth knowing\n\n- **Every generated skill names the exec by first name throughout.** Generic \"the user\" wording is the #1 tell of a low-effort skill — Scout loses persona grounding the moment it slips.\n- **Compliance posture is required, even if \"no material exposure.\"** Microsoft execs operate under SOX and adjacent controls; ignoring compliance is the second-biggest tell.\n- **Partner orgs are listed by name.** Enterprise ops work is cross-functional — Sales, Finance, Engineering, Legal, Risk, Operations, Marketing. Skills that say \"the team\" instead activate weakly.\n- **Self-check checklists in every skill.** Each generated SKILL.md ends with a checklist the skill runs against its own output before delivering. This is the single highest-leverage quality lever.\n- **No fabricated KPIs or quotes.** The templates explicitly forbid invented numbers and require inline citations.\n\n## Adding a new executive\n\n1. Copy `personas/morgan_reyes.yaml` to `personas/<new>.yaml`.\n2. Fill in: `id`, `display_name`, `title`, `org`, `charter`, `scope.process_domains`, `scope.partner_orgs`, `voice_and_style`, `decision_filters`.\n3. Run the generator. No template changes needed.\n\nPrefer not to touch YAML? Build the executive in the web app and click **Export .yaml** to\ndownload a ready-to-commit `personas/<id>.yaml` — then drop it in `personas/` and commit.\n\n## Web app\n\nA browser app aimed at non-technical users — build an executive, preview, and install,\nwithout touching YAML.\n\n```bash\npip install -e \".[web]\"   # or: pip install -r requirements.txt\npython web/app.py         # open http://127.0.0.1:5000\n```\n\nWhat it does:\n\n- **Persona builder** — a plain-language form (name, title, org, charter, KPIs, partners,\n  voice, plus optional support team / cadence / escalation). The server renders skills from\n  the same Python templates the CLI uses, so output is identical.\n- **Skill picker & catalog** — choose which of the eight archetypes to generate from grouped,\n  described cards (each with example triggers and a *recurring* badge), with one-click presets\n  (\"Daily driver,\" \"Leadership review,\" …), Select all / Clear, and a *Browse archetypes*\n  catalog that explains the whole menu.\n- **Live preview** — each skill with its validation errors/warnings, plus the derived\n  automations.\n- **One-click install** — uses the browser **File System Access API** to write\n  `<slug>/SKILL.md` (and `automations/`) straight into the Scout skills folder you pick. The\n  server never touches your local files.\n- **Manage installed skills** — browse the skills already in that folder, grouped by\n  executive, each showing its description and a live validation status (valid / warnings /\n  errors); preview a `SKILL.md` in place, or remove it.\n- **Zip fallback** — browsers without the File System Access API (Safari, Firefox) get a\n  `.zip` to unzip into `~/.copilot/skills/`.\n- **Export persona** — download what you built as a ready-to-commit `personas/<id>.yaml`\n  (the same schema the CLI reads), so a browser-built executive can be seeded into the repo\n  without hand-writing YAML.\n\n### Accounts & persona library (Phase 2)\n\nSigned-in users get a saved **persona library** — Supabase Postgres + email magic-link auth,\nwith row-level security so each library is private to its owner. Generation stays server-side\nand **no-store**; the library is handled browser↔Supabase directly, so the Flask server holds\nno user data or secrets. Enable it by setting `SUPABASE_URL` / `SUPABASE_ANON_KEY` (see\n`web/.env.example`); leave them unset and the app runs library-free.\n\nHosting (Vercel) and the later **Azure + Entra ID** migration path are in\n**[DEPLOY.md](DEPLOY.md)**. Still unverified: the **Scout automation import file schema** —\n`cli/automations.py`'s `automation_to_doc` is the one place to change once confirmed.\n\n## Development\n\n```bash\n# Install (editable) with dev + web extras\npip install -e \".[dev,web]\"      # or: pip install -r requirements.txt\n\n# Run the test suite\npytest\n```\n\nThe validator distinguishes **errors** (block generation / fail `--validate`) from\n**warnings** (surfaced, non-blocking). Beyond the frontmatter spec it enforces the\nquality bar on the body: the executive is named in the first 200 words, the\ndescription carries enough trigger phrases, the self-check has ≥ 5 items, a real Scout\ncapability is referenced, and there's no generic filler. Persona YAML is schema-checked\non load, so a sparse persona fails fast with a clear message instead of rendering empty\nsections.\n\n## License\n\nMIT. See `LICENSE` for details.\n"}