[EmmittJ]

Summary

Adds the skill system design proposal for #162.

Defines the skill-script model — the mechanism for making Squad's storage layer pluggable without locking teams into the Squad CLI runtime. Backend skills are directories in .squad/skills/ containing handler scripts that replace built-in markdown tool handlers in ToolRegistry.

What's covered

• Problem & approaches — why node:fs-hardcoded tools are a structural problem; why npm packages fail the portability constraint; verdicts on prompt injection, platform adapters, MCP servers, and npm packages
• Filesystem audit — complete inventory of every .squad/ path, distinguishing backend-swappable from file-only
• Skill-script model — directory contract, SKILL.md frontmatter, script naming convention, lifecycle hooks (init/dispose), and the case for skills over npm packages
• Configuration — config.json + squad.config.ts surfaces, resolution rules, noop semantics, path containment security, env var expansion
• Handler types — SkillHandler, HandlerLifecycle, per-concern interfaces, ConcernMap, AllHandlers, disjoint-name compile-time assertion, tool argument types
• Loading & resolution — SkillScriptLoader algorithm, startup pipeline, teardown, signal handling, Windows path normalization
• ToolRegistry changes — applySkillHandlers(), handler wrapper, HookPipeline prerequisite
• Platform availability — what activates on CLI vs. @copilot vs. VS Code Chat vs. GitHub.com Chat
• CLI — squad config usage, extended squad doctor output with per-skill validation
• Error handling — startup warnings, runtime failures, lifecycle rollback semantics
• Authoring guide — dev workflow, SDK usage, GitHub Issues skill end-to-end example
• Sharing & distribution — git, copy, submodules, marketplace, personal squad
• Open questions — config validation schema, marketplace trust for executable skills, lazy loading

What this is not

Design proposal only — no code changes. Implementation tracked in #162.

[EmmittJ]

closing as #162 has been cancelled

[bradygaster]

@EmmittJ i actually really liked this idea a lot, and the Squad seemed jazzed about it as well. I'm not sure we didn't do some work inspired by this, I'll check on it. @tamirdresher and got an amazing amount done over the weekend.

[bradygaster]

Yep - as expected, they did that thing they tend to do where they cherry picked part of it during their session. Will make sure to give you credit for this work in the contributors guide.

[bradygaster]

Hey @EmmittJ — wanted to circle back on this. Even though the PR wasn't merged directly, your skill system design proposal had a real impact on what we built.

Over the weekend the team shipped a knowledge-sharing skill system that's clearly inspired by your work here:

What landed (v0.8.21–v0.8.25):

• ✅ .squad/skills/{name}/SKILL.md directory structure with YAML frontmatter — just like you proposed
• ✅ SkillRegistry with keyword + role affinity matching algorithm (packages/squad-sdk/src/skills/)
• ✅ Confidence lifecycle (low → medium → high) for earned knowledge
• ✅ squad_skill runtime tool — agents discover and create skills during work
• ✅ Skill sharing via LocalSkillSource + GitHubSkillSource (export/import)
• ✅ 11 skills live in production today

What we haven't built yet (and think would be great features):

• ❌ Executable handler scripts (JS/TS) that replace built-in tool handlers
• ❌ SkillScriptLoader class for loading and executing handler scripts
• ❌ Lifecycle hooks (on_acquire, on_complete, on_error)
• ❌ ToolRegistry handler replacement mechanism

The team agrees these remaining pieces — especially the executable skill-script layer and ToolRegistry integration — would be excellent features to implement. They'd take the skill system from knowledge-sharing to full extensibility.

We're going to:

1. Credit you in our Contributors Guide for inspiring the skill system
2. Create follow-up issues for the remaining items from your proposal, credited to you
3. If you'd prefer to re-submit PRs for any of that remaining work, we'd love that too — but no pressure, we're happy to carry it forward either way

Thanks for the thoughtful design work. It made a difference. 🚀

[EmmittJ]

@bradygaster I appreciate the credit here! I might have prematurely closed the pr after I saw the issue closed, but I am happy to see a good chunk of it was implemented. I can take a look at the new issue and see if there is anything I can help contribute towards!

Again, thanks for the credit.