feat: v0.4.0-beta.8 — Shared Agent Skills layer + Codex .codex/ support

.agents/skills/before-dev/SKILL.md

@@ -7,7 +7,7 @@ Read the relevant development guidelines before starting your task.
 
 Execute these steps:
 
-1. **Discover available spec modules**:
+1. **Discover packages and their spec layers**:
    ```bash
    python3 ./.trellis/scripts/get_context.py --mode packages
    ```
@@ -22,11 +22,13 @@ Execute these steps:
    ```
    Follow the **"Pre-Development Checklist"** section in the index.
 
-4. **Always read shared guides**:
+4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+5. **Always read shared guides**:
    ```bash
    cat .trellis/spec/guides/index.md
    ```
 
-5. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
 
 This step is **mandatory** before writing any code.

.agents/skills/brainstorm/SKILL.md

@@ -392,14 +392,6 @@ Here's my understanding of the complete requirements:
 Does this look correct? If yes, I'll proceed with implementation.
 ```
 
-### Sync PRD to External Tracker
-
-If lifecycle hooks are configured with a sync action, sync the finalized PRD:
-
-```bash
-TASK_JSON_PATH="$TASK_DIR/task.json" python3 .trellis/scripts/hooks/linear_sync.py sync
-```
-
 ### Subtask Decomposition (Complex Tasks)
 
 For complex tasks with multiple independent work items, create subtasks:

.agents/skills/break-loop/SKILL.md

@@ -5,7 +5,7 @@ description: "Deep post-fix bug analysis across five dimensions: root cause cate
 
 # Break the Loop - Deep Bug Analysis
 
-When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+When debug is complete, use this skill for deep analysis to break the "fix bug -> forget -> repeat" cycle.
 
 ---
 
@@ -61,10 +61,10 @@ What broader problems does this bug reveal?
 Solidify insights into the system:
 
 - [ ] Update `.trellis/spec/guides/` thinking guides
-- [ ] Update `.trellis/spec/cli/backend/` or `cli/frontend/` docs
+- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
 - [ ] Create issue record (if applicable)
 - [ ] Create feature ticket for root fix
-- [ ] Update check commands if needed
+- [ ] Update check skills if needed
 
 ---
 
@@ -121,7 +121,7 @@ Three levels of insight:
    - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
    - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
    - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
-   - If it's domain-specific → update `cli/backend/*.md` or `cli/frontend/*.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
 
 2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
 

.agents/skills/check-cross-layer/SKILL.md

@@ -17,7 +17,7 @@ Check if your changes considered all dimensions. Most bugs come from "didn't thi
 |----------|---------|--------|
 | [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
 | [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
-| **`/trellis:check-cross-layer`** (this) | Verification check | **After** implementation |
+| **`$check-cross-layer`** (this skill) | Verification check | **After** implementation |
 
 ---
 

.agents/skills/check/SKILL.md

@@ -23,7 +23,7 @@ Execute these steps:
    ```
    Follow the **"Quality Check"** section in the index.
 
-4. **Review your code** against each relevant guideline listed in the index.
+4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them.
 
 5. **Run lint and typecheck** for the affected package.
 

.agents/skills/create-command/SKILL.md

@@ -1,94 +1,81 @@
 ---
 name: create-command
-description: "Scaffolds a new slash command in both .cursor/commands/ and .claude/commands/ directories with proper naming conventions and structure. Analyzes requirements to determine command type and generates appropriate content. Use when adding a new developer workflow command, creating a custom slash command, or extending the Trellis command set."
+description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
 ---
 
-# Create New Slash Command
+# Create New Skill
 
-Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories based on user requirements.
+Create a new Codex skill in `.agents/skills/<skill-name>/SKILL.md` based on user requirements.
 
 ## Usage
 
-```
-/trellis:create-command <command-name> <description>
+```bash
+$create-command <skill-name> <description>
 ```
 
 **Example**:
-```
-/trellis:create-command review-pr Check PR code changes against project guidelines
+```bash
+$create-command review-pr Check PR code changes against project guidelines
 ```
 
 ## Execution Steps
 
 ### 1. Parse Input
 
 Extract from user input:
-- **Command name**: Use kebab-case (e.g., `review-pr`)
-- **Description**: What the command should accomplish
+- **Skill name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the skill should accomplish
 
 ### 2. Analyze Requirements
 
-Determine command type based on description:
+Determine skill type based on description:
 - **Initialization**: Read docs, establish context
 - **Pre-development**: Read guidelines, check dependencies
 - **Code check**: Validate code quality and guideline compliance
 - **Recording**: Record progress, questions, structure changes
-- **Generation**: Generate docs, code templates
+- **Generation**: Generate docs or code templates
 
-### 3. Generate Command Content
+### 3. Generate Skill Content
 
-Based on command type, generate appropriate content:
+Minimum `SKILL.md` structure:
 
-**Simple command** (1-3 lines):
 ```markdown
-Concise instruction describing what to do
-```
-
-**Complex command** (with steps):
-```markdown
-# Command Title
-
-Command description
-
-## Steps
-
-### 1. First Step
-Specific action
-
-### 2. Second Step
-Specific action
+---
+name: <skill-name>
+description: "<description>"
+---
 
-## Output Format (if needed)
+# <Skill Title>
 
-Template
+<Instructions for when and how to use this skill>
 ```
 
 ### 4. Create Files
 
-Create in both directories:
-- `.cursor/commands/trellis-<command-name>.md`
-- `.claude/commands/trellis/<command-name>.md`
+Create:
+- `.agents/skills/<skill-name>/SKILL.md`
 
 ### 5. Confirm Creation
 
 Output result:
-```
-[OK] Created Slash Command: /<command-name>
 
-File paths:
-- .cursor/commands/trellis-<command-name>.md
-- .claude/commands/trellis/<command-name>.md
+```text
+[OK] Created Skill: <skill-name>
+
+File path:
+- .agents/skills/<skill-name>/SKILL.md
 
 Usage:
-/trellis:<command-name>
+- Trigger directly with $<skill-name>
+- Or open /skills and select it
 
 Description:
 <description>
 ```
 
-## Command Content Guidelines
+## Skill Content Guidelines
 
-### [OK] Good command content
+### [OK] Good skill content
 
 1. **Clear and concise**: Immediately understandable
 2. **Executable**: AI can follow steps directly
@@ -98,62 +85,17 @@ Description:
 ### [X] Avoid
 
 1. **Too vague**: e.g., "optimize code"
-2. **Too complex**: Single command should not exceed 100 lines
-3. **Duplicate functionality**: Check if similar command exists first
+2. **Too complex**: Single skill should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar skill exists first
 
 ## Naming Conventions
 
-| Command Type | Prefix | Example |
-|--------------|--------|---------|
+| Skill Type | Prefix | Example |
+|------------|--------|---------|
 | Session Start | `start` | `start` |
 | Pre-development | `before-` | `before-dev` |
-| Check | `check-` | `check`, `check-cross-layer` |
+| Check | `check-` | `check` |
 | Record | `record-` | `record-session` |
 | Generate | `generate-` | `generate-api-doc` |
 | Update | `update-` | `update-changelog` |
 | Other | Verb-first | `review-code`, `sync-data` |
-
-## Example
-
-### Input
-```
-/trellis:create-command review-pr Check PR code changes against project guidelines
-```
-
-### Generated Command Content
-```markdown
-# PR Code Review
-
-Check current PR code changes against project guidelines.
-
-## Steps
-
-### 1. Get Changed Files
-```bash
-git diff main...HEAD --name-only
-```
-
-### 2. Categorized Review
-
-**Frontend files** (`apps/web/`):
-- Reference `.trellis/spec/cli/frontend/index.md`
-
-**Backend files** (`packages/api/`):
-- Reference `.trellis/spec/cli/backend/index.md`
-
-### 3. Output Review Report
-
-Format:
-
-## PR Review Report
-
-### Changed Files
-- [file list]
-
-### Check Results
-- [OK] Passed items
-- [X] Issues found
-
-### Suggestions
-- [improvement suggestions]
-```

.agents/skills/finish-work/SKILL.md

@@ -32,9 +32,9 @@ pnpm test
 ### 2. Code-Spec Sync
 
 **Code-Spec Docs**:
-- [ ] Does `.trellis/spec/cli/backend/` need updates?
+- [ ] Does `.trellis/spec/backend/` need updates?
   - New patterns, new modules, new conventions
-- [ ] Does `.trellis/spec/cli/frontend/` need updates?
+- [ ] Does `.trellis/spec/frontend/` need updates?
   - New components, new hooks, new patterns
 - [ ] Does `.trellis/spec/guides/` need updates?
   - New cross-layer flows, lessons from bugs
@@ -55,7 +55,7 @@ If this change touches infra or cross-layer contracts, this is a blocking checkl
 - [ ] Includes required tests and assertion points
 
 **Block Rule**:
-If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `/trellis:update-spec` manually first.
+If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `$update-spec` manually first.
 
 ### 3. API Changes
 
@@ -125,19 +125,19 @@ git diff --name-only
 
 ```
 Development Flow:
-  Write code -> Test -> /trellis:finish-work -> git commit -> /trellis:record-session
+  Write code -> Test -> $finish-work -> git commit -> $record-session
                           |                              |
                    Ensure completeness              Record progress
 
 Debug Flow:
-  Hit bug -> Fix -> /trellis:break-loop -> Knowledge capture
+  Hit bug -> Fix -> $break-loop -> Knowledge capture
                        |
                   Deep analysis
 ```
 
-- `/trellis:finish-work` - Check work completeness (this command)
-- `/trellis:record-session` - Record session and commits
-- `/trellis:break-loop` - Deep analysis after debugging
+- `$finish-work` - Check work completeness (this skill)
+- `$record-session` - Record session and commits
+- `$break-loop` - Deep analysis after debugging
 
 ---