oh-my-customcodex 0.1.0

package/templates/.claude/skills/skill-extractor/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: skill-extractor
+description: Analyze task trajectories to propose reusable SKILL.md candidates from successful patterns
+scope: core
+user-invocable: true
+argument-hint: "[--threshold <n>] [--dry-run]"
+version: 1.0.0
+---
+
+# Skill Extractor
+
+Analyze completed task outcomes to identify reusable patterns and propose new SKILL.md candidates. Inspired by Hermes Agent's self-learning skill extraction — adapted for oh-my-customcodex's compilation metaphor.
+
+## Philosophy
+
+In the compilation metaphor: task trajectories are runtime traces, and extracted skills are new source code. This skill turns successful execution patterns into reusable knowledge artifacts.
+
+```
+Runtime traces (task outcomes) → Pattern analysis → SKILL.md proposal → User approval → mgr-creator
+```
+
+## Usage
+
+```
+/skill-extractor                    # Analyze current session outcomes
+/skill-extractor --threshold 2      # Lower success threshold (default: 3)
+/skill-extractor --dry-run          # Preview proposals without writing
+```
+
+## Options
+
+```
+--threshold, -t   Minimum success count for pattern qualification (default: 3)
+--dry-run, -d     Preview proposals to stdout only, no file writes
+--all             Include all sessions (not just current, requires task outcome history)
+```
+
+## Workflow
+
+### Phase 1: Collect Task Outcomes
+
+Read task outcome data from the session:
+
+```bash
+# Current session outcomes (from task-outcome-recorder hook)
+OUTCOMES_FILE="/tmp/.codex-task-outcomes-${PPID}"
+```
+
+If file doesn't exist or is empty: report "No task outcomes recorded in this session." and stop.
+
+Parse JSONL entries. Each entry has:
+```json
+{"agent_type": "lang-typescript-expert", "skill": "typescript-best-practices", "description": "Fix type error in auth module", "outcome": "success", "model": "sonnet", "timestamp": "2026-04-05T09:30:00Z", "duration_ms": 15000}
+```
+
+### Phase 2: Pattern Detection
+
+Group outcomes by `(agent_type, skill)` tuple:
+
+```
+Pattern: (lang-typescript-expert, typescript-best-practices)
+  → success: 5, failure: 1, total: 6
+  → success_rate: 0.83
+  → descriptions: ["Fix type error...", "Refactor module...", ...]
+```
+
+Filter qualifying patterns:
+- `success_count >= threshold` (default: 3)
+- `success_rate >= 0.8`
+- Not already an existing skill (check `.codex/skills/*/SKILL.md`)
+
+### Phase 3: Generate Proposals
+
+For each qualifying pattern, generate a SKILL.md proposal:
+
+```markdown
+## Proposal: {proposed-skill-name}
+
+**Source Pattern**: {agent_type} + {skill} ({success_count} successes, {success_rate}% rate)
+**Confidence**: {low|medium|high} (based on count and rate)
+
+### Proposed SKILL.md
+
+name: {proposed-name}
+description: {inferred from common description patterns}
+scope: core
+user-invocable: false
+
+### Rationale
+{Why this pattern should be extracted as a skill — based on frequency and success rate}
+
+### Overlap Check
+{List any existing skills with >50% keyword overlap}
+```
+
+**Confidence scoring**:
+| Successes | Rate | Confidence |
+|-----------|------|------------|
+| 3-5 | >= 0.8 | low |
+| 6-10 | >= 0.85 | medium |
+| 10+ | >= 0.9 | high |
+
+### Phase 4: Present to User
+
+Display proposals in ranked order (highest confidence first):
+
+```
+[skill-extractor] {N} skill candidates detected
+
+  1. [high] proposed-skill-name
+     Source: {agent_type} + {skill} (12 successes, 92%)
+     Description: {inferred description}
+
+  2. [medium] another-skill-name
+     Source: {agent_type} + {skill} (7 successes, 86%)
+     Description: {inferred description}
+
+Select [1-N] to create, "all" to create all, or "skip" to cancel:
+```
+
+### Phase 5: Create Skill (on approval)
+
+Delegate to mgr-creator with the proposal context:
+- Proposed name and description
+- Source pattern data
+- Confidence level
+- Any overlap warnings
+
+mgr-creator handles: SKILL.md creation, template sync, ontology registration.
+
+## Integration
+
+| System | How |
+|--------|-----|
+| task-outcome-recorder | Reads JSONL outcomes as input data |
+| feedback-collector | Complementary: feedback-collector extracts failure patterns, skill-extractor extracts success patterns |
+| mgr-creator | Delegated skill creation on user approval |
+| skills-sh-search | Check agentskills.io for existing equivalent before creating |
+| R011 (memory) | User Model tracks extraction decisions in Override Decisions |
+
+## Hook Integration
+
+The `skill-extractor-analyzer.sh` Stop hook provides a lightweight pre-analysis:
+- Reads task outcomes file
+- Counts qualifying patterns
+- Emits advisory stderr message if candidates found
+- Does NOT create skills (that requires user approval via the skill)
+
+## Safety
+
+- **User approval required**: Never auto-creates skills
+- **Overlap check**: Prevents duplicating existing skills
+- **Dry-run mode**: Preview without side effects
+- **Advisory hook**: Stop hook is advisory-only (exit 0)
+- **Confidence transparency**: All proposals show confidence scores

package/templates/.claude/skills/skills-sh-search/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: skills-sh-search
+description: Search and install skills from skills.sh marketplace when internal skills are insufficient
+scope: core
+argument-hint: "<query> [--install] [--global]"
+user-invocable: true
+---
+
+# Skills.sh Search Skill
+
+Search the [skills.sh](https://skills.sh/) marketplace for reusable AI agent skills when no matching internal skill exists. Install discovered skills directly into the project.
+
+## Prerequisites
+
+- Node.js and npx available in PATH
+- Network access to skills.sh registry
+
+## Options
+
+```
+<query>          Required. Search query describing the capability needed
+--install, -i    Install selected skill after search
+--global, -g     Install to ~/.codex/skills/ instead of project .codex/skills/
+--list, -l       List currently installed skills.sh skills
+--check, -c      Check for updates on installed skills.sh skills
+--source, -s     Search source: "skills-sh" (default) | "agentskills" | "all"
+```
+
+## Workflow
+
+```
+1. Search skills.sh marketplace
+   ├── Run: npx --yes skills find "<query>"
+   ├── Review results (name, description, install count)
+   └── Present top candidates to user
+
+2. User selects skill
+   ├── Confirm selection with user
+   └── Check for namespace conflicts with existing skills
+
+3. Install skill
+   ├── Run: npx --yes skills add <source> [-g]
+   ├── Verify installation in .codex/skills/
+   └── Check installed SKILL.md frontmatter
+
+4. Post-install adaptation
+   ├── Review installed SKILL.md frontmatter
+   ├── Add oh-my-customcodex fields if missing:
+   │   ├── user-invocable: true|false
+   │   ├── model-invocable (if not present)
+   │   └── argument-hint (if applicable)
+   └── Add source metadata:
+       ├── source-type: skills-sh
+       └── source-origin: <owner/repo>
+
+5. Ontology sync
+   ├── Notify: run "omcodex ontology build" to register new skill
+   └── Or manually add to skills.yaml if ontology CLI unavailable
+```
+
+## Namespace Conflict Check
+
+Before installing, verify no existing skill shares the same name:
+
+```bash
+# Check for conflict
+ls .codex/skills/ | grep -w "<skill-name>"
+```
+
+If conflict exists:
+- Warn user about the conflict
+- Suggest renaming or skipping
+- Never overwrite existing skills without explicit approval
+
+## Output Format
+
+### Search Results
+```
+[skills-sh-search] Searching marketplace...
+
+Query: "<query>"
+Results: 5 found
+
+  1. owner/skill-name (12.3K installs)
+     Description of the skill
+
+  2. owner/another-skill (8.1K installs)
+     Description of the skill
+
+  3. owner/third-skill (3.5K installs)
+     Description of the skill
+
+Select [1-3] or "skip" to cancel:
+```
+
+### Install Success
+```
+[skills-sh-search] Installed
+
+Skill: <skill-name>
+Source: <owner/repo>
+Location: .codex/skills/<skill-name>/SKILL.md
+Adapted: ✓ (added user-invocable, source metadata)
+
+Next: Run "omcodex ontology build" to register in ontology.
+```
+
+### Install Failure
+```
+[skills-sh-search] Failed
+
+Error: <error_message>
+Suggested Fix: <suggestion>
+```
+
+### No Results
+```
+[skills-sh-search] No Results
+
+Query: "<query>"
+Suggestions:
+  - Try broader search terms
+  - Check https://skills.sh/ directly
+  - Consider creating a custom skill with /create-agent
+```
+
+## Alternative Sources
+
+### agentskills.io (opt-in)
+
+Search the [agentskills.io](https://agentskills.io/) community skill registry as an alternative source.
+
+**Search workflow:**
+```
+1. Try: npx --yes @agentskill.sh/cli search "<query>"
+2. If CLI unavailable: WebSearch "site:agentskills.io <query>"
+3. Present results with source attribution
+```
+
+**Install workflow:**
+```
+1. Run: npx --yes @agentskill.sh/cli install <slug>
+2. Verify installation in .codex/skills/
+3. Add source metadata:
+   ├── source-type: agentskills-io
+   └── source-origin: <slug>
+```
+
+**Usage:**
+```bash
+# Search agentskills.io only
+/skills-sh-search "memory management" --source agentskills
+
+# Search both sources
+/skills-sh-search "testing patterns" --source all
+```
+
+**Fallback chain:**
+| Step | Tool | Condition |
+|------|------|-----------|
+| 1 | `@agentskill.sh/cli search` | Primary — if CLI available |
+| 2 | `WebSearch site:agentskills.io` | CLI unavailable or no results |
+| 3 | Report no results | Both failed |
+
+## Examples
+
+```bash
+# Search for Terraform skills
+/skills-sh-search terraform infrastructure
+
+# Search and install
+/skills-sh-search "react testing patterns" --install
+
+# Install globally
+/skills-sh-search "git workflow" --install --global
+
+# List installed skills.sh skills
+/skills-sh-search --list
+
+# Check for updates
+/skills-sh-search --check
+
+# Search agentskills.io
+/skills-sh-search "agent memory" --source agentskills
+
+# Search all sources
+/skills-sh-search "code review" --source all --install
+```
+
+## Integration
+
+### With intent-detection
+When intent-detection finds no matching agent and the domain is identifiable, this skill can be suggested as a fallback to find relevant external skills.
+
+### With update-external
+Installed skills.sh skills are tracked with `source-type: skills-sh` metadata, enabling `update-external` to check for updates via `npx skills check`.
+
+### With create-agent
+If a skills.sh skill provides domain knowledge, `create-agent` can reference it when building a new agent for that domain.
+
+### With agentskills.io
+Installed agentskills.io skills are tracked with `source-type: agentskills-io` metadata, enabling `update-external` to check for updates. Default source remains skills.sh; agentskills.io is opt-in via `--source` flag.
+
+## Safety
+
+- **Read-only by default**: Search does not modify anything
+- **Explicit install**: Installation requires `--install` flag or user confirmation
+- **No auto-execution**: Installed skills are not auto-invoked without ontology registration
+- **Conflict protection**: Never overwrites existing skills
+- **Telemetry opt-out**: Set `DISABLE_TELEMETRY=1` to disable skills CLI telemetry

package/templates/.claude/skills/snowflake-best-practices/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: snowflake-best-practices
+description: Snowflake best practices for cloud data warehouse design, query optimization, and cost management
+scope: core
+user-invocable: false
+---
+
+# Snowflake Best Practices
+
+## Warehouse Design
+
+### Sizing (CRITICAL)
+- Start small (XS or S), scale up as needed
+- Enable auto-scaling for concurrency
+- Enable auto-suspend (1 minute idle)
+- Separate warehouses for different workloads
+
+### Multi-Cluster Warehouses
+- Use for high concurrency (many users)
+- Set min/max clusters based on load
+- Scaling policy: Standard (default) or Economy
+
+## Query Optimization
+
+### Clustering Keys (CRITICAL)
+- Define clustering keys for frequently filtered columns
+- Improves micro-partition pruning
+- Monitor clustering depth
+- Automatic clustering: `ALTER TABLE ... CLUSTER BY (...)`
+
+### Result Caching
+- 24-hour cache for identical queries
+- Use SHOW PARAMETERS to check cache status
+- Bypass cache with query hint: `/*+ NO_RESULT_CACHE */`
+
+### Materialized Views
+- For repeated aggregations
+- Automatically refreshed on base table changes
+- Cost: storage + refresh compute
+
+## Data Loading
+
+### COPY INTO (CRITICAL)
+- Batch load from stages (S3/GCS/Azure)
+- File size: 100-250MB compressed (optimal)
+- Use pattern matching for multiple files
+
+### Snowpipe
+- Continuous ingestion
+- Event-driven (S3 notifications)
+- Serverless compute
+
+## Cost Optimization
+
+### Resource Monitors
+- Set credit quotas per warehouse
+- Alerts and suspend actions
+- Track consumption with WAREHOUSE_METERING_HISTORY
+
+### Storage
+- Use zero-copy cloning for dev/test
+- Time travel retention: 1 day (standard), 90 days (enterprise)
+- Fail-safe: 7 days (not configurable)
+
+## References
+- [Snowflake Best Practices](https://docs.snowflake.com/en/user-guide/best-practices)

package/templates/.claude/skills/spark-best-practices/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: spark-best-practices
+description: Apache Spark best practices for PySpark and Scala distributed data processing
+scope: core
+user-invocable: false
+---
+
+# Apache Spark Best Practices
+
+## Performance Optimization
+
+### Broadcast Joins (CRITICAL)
+- Use `broadcast(small_df)` for small-large table joins
+- Default broadcast threshold: 10MB (`spark.sql.autoBroadcastJoinThreshold`)
+- Avoid broadcast for tables > 100MB
+
+### Shuffles (CRITICAL)
+- Minimize shuffles: expensive operations
+- Use `coalesce()` to reduce partitions without shuffle
+- Use `repartition()` only when necessary (causes shuffle)
+- Predicate pushdown: filter before joins
+
+### Caching
+- Cache DataFrames used multiple times: `df.cache()` or `df.persist()`
+- Choose storage level: MEMORY_ONLY, MEMORY_AND_DISK, DISK_ONLY
+- Unpersist when done: `df.unpersist()`
+
+## Resource Management
+
+### Executor Configuration
+- Executor memory: 80% of available memory per executor
+- Executor cores: 4-5 cores per executor (optimal)
+- Dynamic allocation: enable for varying workloads
+
+### Partitioning
+- Optimal partition size: 100-200MB
+- Too few partitions: underutilized cluster
+- Too many partitions: task overhead
+
+## Data Processing
+
+### UDFs
+- Prefer built-in functions over UDFs
+- Use Pandas UDF for vectorized operations
+- Avoid Python UDFs (serialization overhead)
+
+### Storage Formats
+- Parquet: default for analytics (columnar, compression)
+- ORC: alternative to Parquet
+- Delta/Iceberg: ACID transactions, time travel
+
+## References
+- [Spark Performance Tuning](https://spark.apache.org/docs/latest/tuning.html)

package/templates/.claude/skills/springboot-best-practices/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: springboot-best-practices
+description: Spring Boot patterns for enterprise Java applications
+scope: core
+user-invocable: false
+---
+
+## Rules
+
+### 1. Project Structure
+Layered architecture: controller (REST), service (business logic), repository (data access), model/entity, dto, config, exception.
+
+### 2. Dependency Injection
+Constructor injection preferred. Use @RequiredArgsConstructor with final fields. Avoid field injection with @Autowired.
+
+```java
+// GOOD: Constructor injection
+@Service
+@RequiredArgsConstructor
+public class UserService {
+    private final UserRepository userRepository;
+    private final EmailService emailService;
+}
+```
+
+### 3. REST API Design
+@RestController + @RequestMapping. Use @Validated for input, ResponseEntity for responses, proper HTTP status codes.
+
+See `examples/controller-example.java` for reference implementation.
+
+### 4. Service Layer
+Business logic in services. @Transactional boundaries at service level. Interface + implementation pattern.
+
+See `examples/service-example.java` for reference implementation.
+
+### 5. Data Access
+Spring Data JPA. @Query or method naming for custom queries. @Entity with proper JPA annotations.
+
+See `examples/repository-example.java` and `examples/entity-example.java` for reference implementations.
+
+### 6. Exception Handling
+@RestControllerAdvice for global handling. Domain-specific exceptions with proper HTTP status mapping.
+
+See `examples/exception-handler-example.java` for reference implementation.
+
+### 7. Configuration
+Profile-based: application-{profile}.yml. @ConfigurationProperties for type-safe config. Externalize sensitive values.
+
+```yaml
+# application.yml
+spring:
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:local}
+  datasource:
+    url: ${DATABASE_URL}
+    username: ${DATABASE_USERNAME}
+    password: ${DATABASE_PASSWORD}
+```
+
+See `examples/config-properties-example.java` for type-safe configuration properties.
+
+### 8. Security
+Spring Security with SecurityFilterChain. Externalize secrets. Proper authentication/authorization patterns.
+
+See `examples/security-config-example.java` for reference implementation.
+
+### 9. Testing
+@WebMvcTest (controller), @DataJpaTest (repository), @SpringBootTest (integration), @MockBean for mocking.
+
+See `examples/controller-test-example.java` and `examples/repository-test-example.java` for reference implementations.
+
+## Application
+
+Always: constructor injection, layered architecture, DTOs, global exception handling, externalized config, proper security, layer-appropriate tests.

package/templates/.claude/skills/springboot-best-practices/examples/config-properties-example.java

@@ -0,0 +1,22 @@
+package com.example.demo.config;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.validation.annotation.Validated;
+
+@Configuration
+@ConfigurationProperties(prefix = "app")
+@Validated
+@Getter
+@Setter
+public class AppProperties {
+    @NotBlank
+    private String name;
+
+    @Min(1)
+    private int maxConnections;
+}

package/templates/.claude/skills/springboot-best-practices/examples/controller-example.java

@@ -0,0 +1,28 @@
+package com.example.demo.controller;
+
+import com.example.demo.dto.UserRequest;
+import com.example.demo.dto.UserResponse;
+import com.example.demo.service.UserService;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+@RestController
+@RequestMapping("/api/v1/users")
+@RequiredArgsConstructor
+public class UserController {
+    private final UserService userService;
+
+    @GetMapping("/{id}")
+    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
+        return ResponseEntity.ok(userService.findById(id));
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public UserResponse createUser(@Valid @RequestBody UserRequest request) {
+        return userService.create(request);
+    }
+}

package/templates/.claude/skills/springboot-best-practices/examples/controller-test-example.java

@@ -0,0 +1,33 @@
+package com.example.demo.controller;
+
+import com.example.demo.dto.UserResponse;
+import com.example.demo.service.UserService;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.mockito.BDDMockito.given;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;
+
+    @Test
+    void getUser_shouldReturnUser() throws Exception {
+        given(userService.findById(1L))
+            .willReturn(new UserResponse(1L, "test@example.com"));
+
+        mockMvc.perform(get("/api/v1/users/1"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.email").value("test@example.com"));
+    }
+}

package/templates/.claude/skills/springboot-best-practices/examples/entity-example.java

@@ -0,0 +1,22 @@
+package com.example.demo.entity;
+
+import jakarta.persistence.*;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Entity
+@Table(name = "users")
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class User {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false, unique = true)
+    private String email;
+
+    @Enumerated(EnumType.STRING)
+    private UserStatus status;
+}

package/templates/.claude/skills/springboot-best-practices/examples/exception-handler-example.java

@@ -0,0 +1,30 @@
+package com.example.demo.exception;
+
+import com.example.demo.dto.ErrorResponse;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.ResponseStatus;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.util.List;
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(UserNotFoundException.class)
+    @ResponseStatus(HttpStatus.NOT_FOUND)
+    public ErrorResponse handleUserNotFound(UserNotFoundException ex) {
+        return new ErrorResponse("USER_NOT_FOUND", ex.getMessage());
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    @ResponseStatus(HttpStatus.BAD_REQUEST)
+    public ErrorResponse handleValidation(MethodArgumentNotValidException ex) {
+        List<String> errors = ex.getBindingResult()
+            .getFieldErrors()
+            .stream()
+            .map(e -> e.getField() + ": " + e.getDefaultMessage())
+            .toList();
+        return new ErrorResponse("VALIDATION_ERROR", errors);
+    }
+}