User-global custom skills/commands (with override precedence, like schemas) #757

Activity

1. 21st-connector commented on Feb 24, 2026

   

   21st-connectorBot

   on Feb 24, 2026 – with 21st - Connector

   Last edited by 21st-connector

   Contributor

   More actions

   Task completed.

   The enrichment comment has been posted on issue #757. Here's a summary of what was included:

   Existing precedent: The codebase already has a three-tier schema override system (resolver.ts:63-91) with project-local > user-global > package built-in precedence, using XDG directories (global-config.ts:66-87). This pattern directly informs how skills/commands overrides should work.

   Current architecture: Skills/commands are generated from hardcoded TypeScript templates in src/core/templates/workflows/ with no external discovery mechanism. Key integration points for the feature are in skill-generation.ts, init.ts, and update.ts.

   Suggested approach: Mirror the schema resolver pattern -- add getUserSkillsDir()/getUserCommandsDir() functions, create a merge layer in getSkillTemplates() that discovers user-global overrides, and validate user files against existing interfaces.

   Related issues: Linked 6 related open issues including #752 (global install), #756 (user-level schemas), #689 (standard skills folder), #590 (packaged skills), #611 (context bloat), and #350 (custom paths).

   Design question input: Noted that the existing workflows array in GlobalConfig already provides a disable mechanism for built-in skills, and that the SKILL.md YAML frontmatter format could serve as the canonical format for user-defined skills.

   ---

   View full conversation

   Powered by 1Code
2. 21st-connector commented on Feb 24, 2026

   

   21st-connectorBot

   on Feb 24, 2026 – with 21st - Connector

   Contributor

   More actions

   Issue Enrichment: Codebase Analysis

   Thanks for the detailed proposal, @askpatrickw. Here's an analysis of the existing codebase to help inform implementation.

   ---

   Existing Precedent: Schema Override System

   OpenSpec already implements a three-tier precedence system for schemas that this feature would mirror. The resolution logic is in src/core/artifact-graph/resolver.ts:63-91:

   1. Project-local:  <projectRoot>/openspec/schemas/<name>/  (highest)
   2. User-global:    ~/.local/share/openspec/schemas/<name>/
   3. Package built-in: <npm-package>/schemas/<name>/          (lowest)
   

   Global directory paths are defined in src/core/global-config.ts:66-87 using XDG Base Directory Specification:

   • Linux/macOS: ~/.local/share/openspec/ (via XDG_DATA_HOME)
   • Windows: %LOCALAPPDATA%/openspec/

   The listSchemasWithInfo() function in resolver.ts:224-302 already tracks source: 'project' | 'user' | 'package' and which schemas shadow others. This pattern can be directly reused for skills/commands.

   ---

   Current Skills/Commands Architecture

   Skills and commands are generated from hardcoded TypeScript template functions in src/core/templates/workflows/ (11 workflows). There is no mechanism to discover or load external skill/command definitions.

   Key files involved in generation:

   File	Role
   src/core/shared/skill-generation.ts	getSkillTemplates(), getCommandContents(), generateSkillContent()
   src/core/command-generation/generator.ts	generateCommands() using tool-specific adapters
   src/core/command-generation/registry.ts	CommandAdapterRegistry - 24 tool adapters
   src/core/init.ts:499-597	generateSkillsAndCommands() - init flow
   src/core/update.ts:170-244	Update flow (same pattern)

   Generation flow:

   1. Read global config for profile/delivery settings (src/core/global-config.ts)
   2. Filter templates by profile workflows (src/core/profiles.ts)
   3. For each selected tool: write SKILL.md files and tool-specific command files via adapters

   Skills currently use a SkillTemplate interface (src/core/templates/types.ts):

   interface SkillTemplate {
     name: string;
     description: string;
     instructions: string;
     license?: string;
     compatibility?: string;
     metadata?: Record<string, string>;
   }

   Commands use a CommandContent interface (src/core/command-generation/types.ts):

   interface CommandContent {
     id: string;
     name: string;
     description: string;
     category: string;
     tags: string[];
     body: string;
   }

   ---

   Suggested Implementation Approach

   Based on the existing architecture, a natural approach would be:

   1. Global directories (following schema pattern from global-config.ts):

   ~/.local/share/openspec/skills/<skill-dir-name>/SKILL.md
   ~/.local/share/openspec/commands/<command-id>.md
   

   2. Resolution functions (mirror resolver.ts pattern):

   • getUserSkillsDir() / getUserCommandsDir() in global-config.ts
   • A getSkillTemplatesWithOverrides() function that:
     1. Loads built-in templates from src/core/templates/workflows/
     2. Scans user-global directory for overrides/additions
     3. Merges with user-global taking precedence on name match

   3. Integration points - The main changes would be in:

   • src/core/shared/skill-generation.ts - Add user-global skill discovery to getSkillTemplates()
   • src/core/init.ts:517-527 - Merge user-global templates before generation
   • src/core/update.ts:170-171 - Same merge in update flow
   • src/commands/schema.ts - Model for a potential openspec skill which / openspec skill list command

   4. Validation - Parse and validate user-provided SKILL.md files against the SkillTemplate interface before overlay (similar to resolveSchema() in resolver.ts:109-153 which validates via Zod).

   ---

   Related Issues

   Several open issues are directly related or would benefit from this work:

   • openspec init --global: Install skills and commands to tool global directories #752 - openspec init --global: Install skills and commands to tool global directories (complementary - addresses tool-global install, this addresses user-global definitions)
   • Add --user option to openspec schema init for user-level schemas #756 - Add --user option to openspec schema init for user-level schemas (same pattern, schema side)
   • Proposal: use a standard .agent/skills folder for all agents that support it #689 - Proposal: use a standard .agent/skills folder for all agents (related standardization)
   • Proposal: bundle related skills into a packaged skill structure #590 - Bundle related skills into a packaged skill structure (could define the packaging format)
   • Are skills even necessary? why bloat context with 10 openspec skills? #611 - Are skills even necessary? Why bloat context with 10 openspec skills? (context bloat concern - validation in this feature could help by allowing users to selectively override/disable)
   • Feature Request: Add support for custom command directory paths during openspec init #350 - Add support for custom command directory paths during openspec init

   ---

   Open Design Questions

   Re: Deletion/masking - The schema system doesn't currently support disabling/tombstoning a built-in. Options:

   1. A disabled field in ~/.config/openspec/config.json (extends GlobalConfig interface in global-config.ts:15-20)
   2. A tombstone file convention (e.g., ~/.local/share/openspec/skills/openspec-explore/.disabled)
   3. Leveraging the existing workflows array in GlobalConfig - users already can filter which workflows are active via openspec config profile

   Option 3 is notable because the workflows filter in GlobalConfig already controls which skills get generated. A user wanting to "disable" a built-in skill could simply remove it from their workflow list. Custom skills would need a separate mechanism.

   Re: Project-local overrides - The schema system already supports this tier (getProjectSchemasDir() in resolver.ts:44-46). Adding project-local skills/commands would complete the three-tier model: project > user-global > package.

   Re: Skill file format - User-defined skills would need a parseable format. The existing SKILL.md with YAML frontmatter (as generated by generateSkillContent() in skill-generation.ts:127-149) could serve as the canonical format for user-defined skills too.
3. askpatrickw commented on Feb 26, 2026

   

   askpatrickw

   on Feb 26, 2026

   Author

   More actions

   I no longer think this is needed. Use a tool like Skillshare to roll out skills globally across all agents and all developers.
4. askpatrickw

   closed this as completedon Feb 26, 2026