Skills Strategy — Atlas + Sush¶

Status: Living doc · Started 21 May 2026 · Sibling to memory-system-architecture.md Owner: Sush + Atlas Purpose: A single source of truth for which skills we build, why, how, and what NOT to skill. Triggers when: Any session that proposes a new skill, refactors an existing one, or evaluates skill ROI.

0. Why this exists¶

Sush already has 14 spec-compliant skills sitting at C:\Users\ssutheesh\.copilot\skills\ and doesn't use them. That means the bottleneck is not infrastructure — it's discoverability, voice fit, and trigger reliability. Any new skill we add must clear higher bars than just "compiles." This doc keeps us honest.

1. The agentskills.io spec in one page¶

Anatomy¶

skill-name/
├── SKILL.md           # REQUIRED · YAML frontmatter + instructions body
├── scripts/           # OPTIONAL · executable code
├── references/        # OPTIONAL · deeper docs (often called modules/ here)
├── assets/            # OPTIONAL · templates, schemas, lookups
└── evals/             # OPTIONAL but strongly recommended
    └── evals.json     # Test cases + assertions

SKILL.md frontmatter (canonical)¶

Field	Req	Constraints
`name`	✓	1–64 chars, `[a-z0-9-]`, no leading/trailing/consecutive hyphens, MUST match folder name
`description`	✓	1–1024 chars. Tells the agent WHAT it does AND WHEN to use it. Imperative voice. List trigger contexts.
`license`	−	Short license name or filename ref
`compatibility`	−	Environment requirements (only if non-trivial)
`metadata`	−	Arbitrary key-value (we'll use this for our extensions — see §5)
`allowed-tools`	−	Experimental pre-approved tools list

Progressive disclosure — the load model¶

Level 1 — Metadata (~100 tokens/skill, always loaded): name + description only
Level 2 — Body (< 5000 tokens, loaded on activation): the SKILL.md markdown body
Level 3+ — Files (loaded on demand): referenced files in references/, scripts/, assets/

Hard rule: keep SKILL.md under 500 lines / 5k tokens. Push detail to referenced files with explicit "load this when X" instructions.

When skills trigger (mental model)¶

Agents only consult skills for tasks needing capability beyond what they can do alone. A simple "read this PDF" might not fire the PDF skill — but "extract form fields and validate against schema" will. Implication: skills that just rephrase what the agent already does won't get used. This is the #1 reason existing skills sit dormant.

Description-writing rules (extracted from spec + best practices)¶

Imperative voice: "Use this skill when…" not "This skill does…"
List explicit trigger contexts, including indirect ones: "even if they don't explicitly mention 'CSV' or 'analysis.'"
Err pushy — under-triggering is worse than over-triggering for skills you actually want used
Test with eval queries — 8–10 should-trigger + 8–10 should-not-trigger (near-miss negatives), 3 runs each, target ≥0.5 trigger rate on positives

2. The meta-principles (Sush's rules, formalised)¶

Every skill we build/keep must pass all four gates:

Gate 1 — Voice test¶

Any output a skill produces in Sush's voice MUST pass: brag-allergy check, "for people like us" plain English, no forbidden words (frontier, ecosystem, agentic, robust, scalable, mission-critical, holistic, AI-powered).
For customer-facing output: skill must follow the Sush's Voice Rule (ask what he genuinely thinks first, then craft).
For autonomous output: skill must include the Atlas signature (Rule #3) if it sends anything.

Gate 2 — Quality test (eval-driven)¶

Every skill MUST have evals/evals.json with at least 3 test cases (one happy path, one edge case, one trigger-test).
Run with-skill vs without-skill comparison — if the without-skill output is just as good, the skill adds zero value and should be deleted.
Assertions must be observable (no "the output is good" — instead "the output contains a 3-row table with column X").

Gate 3 — Last-used stamp¶

Each skill carries metadata.last_used and metadata.use_count in YAML frontmatter.
A skills-meta skill (see §6) reviews this monthly. Any skill not used in 90 days gets flagged for either:
Resurrect: fix description so it triggers, OR
Retire: archive to ~/.copilot/skills/_retired/
No silent rot. Either it earns its place or it goes.

Gate 4 — Meta-review¶

Every new skill submitted via the skills-meta skill before going live. Checks:
Spec compliance (frontmatter, naming, body size)
Voice rules compliance
Eval set exists and assertions are observable
description field tested against trigger eval queries
Failing the meta-review is a blocker, not a warning.

3. What's already there (audit summary)¶

Folder: C:\Users\ssutheesh\.copilot\skills\

Bundled (don't touch unless porting voice): - docx, pptx, xlsx — Anthropic document skills - excalidraw, loop, expense-report — Clawpilot bundled - web-artifacts-builder — Clawpilot bundled - azure-deploy, data-ai-toolkit, security-scanner — Clawpilot bundled

CSA/DSSP coach pack (Sush doesn't use — verified 21 May 2026): - acr-signal-to-opportunity-coach - customer-meeting-prep-outreach-coach - forecast-business-review-coach - funding-partner-activation-coach - pipeline-msx-hygiene-coach - portfolio-account-planning-coach - solution-value-design-coach

Why these don't trigger (hypothesis): descriptions are written for generic CSA/DSSP workflows. Sush's actual prompts ("help me prep for the X customer call tomorrow") don't match. The skills assume CRM/MSX data access patterns Sush doesn't use in everyday Clawpilot prompts.

Decision (21 May 2026): leave them in place but de-prioritise. Focus energy on Categories B + C below. If a CSA-pack skill becomes useful later, fix its description rather than rebuild.

Brilliant pattern to mirror: skills/shared/ already holds cross-skill voice rules, source-attribution templates, MSX permission matrix, evals. We'll extend this with Sush voice rules and Atlas signature templates so every new skill can references/SHARED/voice-rules.md.

Category B — Ad-hoc prompts → skills (build order priority)¶

#	Skill name	Trigger frequency	Source pattern	Build priority
B1	`voice-review`	every customer-facing output	scattered rules in instructions.md	P0 — gates everything else
B2	`connect-classify`	weekly (#connect codeword)	already documented inline	P0 — Sush's flagship workflow
B3	`customer-meeting-debrief`	weekly	currently ad-hoc	P1
B4	`question-enrichment`	daily during Q&A builds	scattered prompts	P1
B5	`sme-review`	every blog/learn-doc	ad-hoc	P1
B6	`qa-review`	every deploy	partly in deployment-playbook	P2
B7	`blog-post-writer`	weekly	notebook-system docs	P2
B8	`cosmos-planet-revision`	monthly	cosmos-philosophy doc	P3
B9	`multiplier-network-coach`	quarterly (FY27 Connect prep)	session files only	P3

Rule: P0 first, both ship before any P1. P3s only if used ≥ monthly when the time comes.

Category C — Scripts → skills (build order priority)¶

#	Skill name	Wraps script	Use cadence	Priority
C1	`gsc-weekly`	`gsc-weekly.py`	every Sunday	P0
C2	`stripe-weekly`	`stripe-weekly.py`	every Sunday	P0
C3	`realtime-check`	`realtime-probe.py`	every Sunday + on-demand	P0
C4	`cosmos-qa`	`qa-audit.mjs`	every Cosmos deploy	P1
C5	`guided-qa`	`test-guided-qa.cjs`	every Guided deploy	P1
C6	`wip-audit`	`audit-wip.ps1`	every session start	P1
C7	`hugo-safe`	`hugo-safe.ps1`	every hugo build/serve	P2
C8	`trim-journal`	`trim-journal.py`	when journal > 60KB	P3

Rule: Category C is cheap. SKILL.md just invokes the existing script with arg passthrough. P0 trio first because the Sunday ritual is mandatory.

Category D — Will NOT build (saying no out loud)¶

One-off creative work (each blog post is unique enough)
Skills used < monthly (B9 stays P3 until proven)
Skills whose work the base agent already does well (test with eval — if without-skill matches with-skill, no skill)
Skills that just wrap a single short prompt with no scripts/references (just keep the prompt in memory)

5. Atlas extensions to the spec (our conventions)¶

We use the spec's metadata field for our own tracking. Reserved keys (always prefix atlas.):

---
name: voice-review
description: ...
metadata:
  atlas.last_used: "2026-05-21"
  atlas.use_count: 7
  atlas.voice_critical: true       # skill output goes out in Sush voice
  atlas.atlas_signature: false     # whether skill sends autonomous messages (Rule #3)
  atlas.cowork_relevant: true      # surfaces in CSA day-job, not personal
  atlas.surface: "both"            # clawpilot | cli | both
  atlas.review_due: "2026-08-21"   # quarterly review date
---

Shared resources folder¶

Extend ~/.copilot/skills/shared/ with: - references/atlas-voice-rules.md — brag-allergy check, forbidden words, plain English rules - references/atlas-signature-templates.md — email + Teams footer text (Rule #3) - references/sush-decision-rights.md — what needs explicit bypass (Rule #2) vs what's auto-OK - templates/sush-customer-email.md — voice-aware customer email starter - templates/connect-classify-buckets.md — the 10 buckets reference

Any new skill can references/SHARED/atlas-voice-rules.md instead of re-stating rules.

6. The `skills-meta` skill (self-policing)¶

The keystone skill. Inputs: a skill folder path (or all for full audit). Outputs:

~/.copilot/skills/SKILL-META-REPORT.md
├── Spec compliance per skill (frontmatter, naming, body size)
├── Voice rules compliance (forbidden words, brag-allergy, plain English)
├── Eval suite present + assertions observable
├── Description tested against trigger queries (pass rate per skill)
├── Last-used staleness (90-day flag list)
└── Suggested actions per skill (fix | retire | resurrect | OK)

Triggers: monthly cadence + before any new skill ships. This is what keeps the skill library from rotting.

7. Build order (concrete)¶

Foundation pass (this session or next):
Extend skills/shared/references/ with Atlas voice rules + signature templates + decision rights (the rules we cite everywhere)
Build skills-meta skeleton (the self-policing skill)
Build voice-review (B1, P0) — gates every other voice-touching skill
Build connect-classify (B2, P0) — Sush's flagship workflow
Sunday ritual pass:
Wrap C1/C2/C3 (gsc-weekly, stripe-weekly, realtime-check) as thin script-wrapper skills
Co-work pass:
Build B3 customer-meeting-debrief, B4 question-enrichment, B5 sme-review
Deploy ritual pass:
Wrap C4 cosmos-qa, C5 guided-qa, C6 wip-audit
Run first skills-meta audit. Fix anything failing. Establish baseline.
Quarterly review cadence — first one due ~ Aug 2026. Retire what hasn't fired.

8. What to do when an existing skill doesn't trigger¶

The 7 CSA coach skills + the bundled ones are the test case for this. If a skill exists and isn't being used:

Run description eval (8–10 queries from real Sush usage). Measure trigger rate.
Read execution traces (if any) — does it activate but produce useless output? Or does it never activate?
Fix in this order:
Description (most common fix — rewrite to imperative voice, list explicit trigger contexts)
Body content (too generic? doesn't match Sush's actual workflow?)
Sub-files (modules/ wrong granularity?)
If after 2 description rewrites it still doesn't trigger: archive to _retired/ and move on. Don't sunk-cost.

9. Open questions (for Sush)¶

Should we port skills to a Codex-compatible location too (.agents/skills/ in repos), or keep them Claude/Clawpilot only for now?
Should skills-meta send a Teams summary of the monthly audit (with Atlas signature per Rule #3), or just write the report file?
Are there workflows I'm missing in Category B/C? This list is from instructions + memory + journal. There may be workflows Sush does that haven't been captured anywhere yet.

10. References¶

Spec: https://agentskills.io/specification.md
Best practices: https://agentskills.io/skill-creation/best-practices.md
Description optimisation: https://agentskills.io/skill-creation/optimizing-descriptions.md
Eval-driven iteration: https://agentskills.io/skill-creation/evaluating-skills.md
Scripts in skills: https://agentskills.io/skill-creation/using-scripts.md
Anthropic engineering blog: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
Anthropic skills repo (examples): https://github.com/anthropics/skills
Validator: npx skills-ref validate ./my-skill

Changelog¶

2026-05-21 — Created. Spec read end-to-end. Existing skills audited (14 found, mostly unused). Build list scoped to Categories B + C. Atlas extensions defined. Meta-principles (voice/quality/last-used/meta-review) formalised.