Skill File Assembly

Overview

Combine generated frontmatter with processed template content to create the final, complete skill file ready for saving.

Assembly Process

<assembly_flow>

Step 1: Prepare Components

Gather all components needed for assembly.

<component_collection> REQUIRED_COMPONENTS: - Frontmatter (from generate-frontmatter.md) - Template content (from replace-markers.md) - Improvement metadata (if mode == "analyze")

VALIDATE: - Frontmatter is valid YAML - Template content is fully processed (no unresolved markers) - All required sections present - Code examples properly formatted </component_collection>

Step 2: Assemble File Structure

Combine components into final structure.

<assembly_structure> FINAL_FILE_FORMAT: 1. YAML frontmatter (enclosed in ---) 2. Blank line 3. Main content (processed template) 4. Footer (optional metadata)

EXAMPLE_STRUCTURE: ```markdown --- name: my-app-api-patterns description: Spring Boot API patterns for my-app version: 3.2.0 framework: spring-boot globs: - "src//*Controller.java" - "src//*Service.java" ---

# Spring Boot API Patterns

[Template content...]

---

*Generated by Agent OS Add Skill Command*
```

</assembly_structure>

<assembly_algorithm> STEP_BY_STEP: 1. Start with empty string 2. Add frontmatter YAML (with --- delimiters) 3. Add single blank line 4. Add main content 5. Ensure proper line endings (LF, not CRLF) 6. Add footer if configured 7. Validate complete file

PSEUDOCODE: skill_content = "" skill_content += "---\n" skill_content += frontmatter_yaml skill_content += "---\n\n" skill_content += processed_template_content skill_content += "\n\n---\n\n" skill_content += footer_content </assembly_algorithm>

Step 3: Format Sections

Ensure consistent formatting throughout the file.

<section_formatting> HEADING_HIERARCHY: - # (h1): Main title only (once) - ## (h2): Major sections - ### (h3): Subsections - #### (h4): Detailed subsections (use sparingly)

SPACING: - Blank line before each heading - Blank line after each heading - Blank line between sections - Blank line before and after code blocks

CODE_BLOCKS: - Always specify language (java, typescript, etc.) - Consistent indentation (2 spaces) - Add descriptive comments - Keep examples focused (< 40 lines)

LISTS: - Use consistent bullet style (-) - Indent nested lists by 2 spaces - Blank line before and after lists

EMPHASIS: - Bold for important terms - Code for inline code - ✅ ❌ ⚠️ Emojis for status indicators </section_formatting>

Step 4: Add Improvement Annotations

Mark sections that were enhanced with improvements.

<improvement_annotations> IF mode == "analyze" AND improvements_applied > 0: FOR each section with applied_improvement: ADD_ANNOTATION: Above or within section

  ANNOTATION_FORMAT:
    "✅ **Enhanced with Improvement:** {improvement_title}
     {brief_description}"

  EXAMPLE:
    ```markdown
    ## Error Handling

    ✅ **Enhanced with Improvement:** Centralized Exception Handling
    This pattern was added to replace duplicated error handling across controllers.

    ### Global Exception Handler
    ```java
    @ControllerAdvice
    public class GlobalExceptionHandler {
        // ...
    }
    ```
    ```

IMPROVEMENT_SUMMARY_SECTION: IF improvements_applied > 0: ADD_SECTION: Near beginning of content

  CONTENT:
    "## Improvements Applied

     This skill includes {count} improvements to enhance code quality:

     Critical:
     - {improvement_1}
     - {improvement_2}

     Warnings:
     - {improvement_3}
     - {improvement_4}

     These improvements are integrated into the relevant sections below.
     "

</improvement_annotations>

Step 5: Validate Assembled Content

Ensure the complete file is valid and ready to save.

<validation_checks> FRONTMATTER_VALIDATION: - Valid YAML syntax - All required fields present (name, description, globs) - No parsing errors - Proper --- delimiters

CONTENT_VALIDATION: - No unresolved markers remaining - All sections present - Code blocks have language identifiers - No empty required sections - Proper markdown syntax

STRUCTURE_VALIDATION: - Single h1 heading (title) - Logical heading hierarchy (no jumps from h2 to h4) - Sections in logical order - Consistent formatting

SIZE_VALIDATION: - File size reasonable (< 500 KB) - Line count reasonable (< 10000 lines) - Not too small (> 100 lines minimum)

ENCODING_VALIDATION: - UTF-8 encoding - LF line endings (not CRLF) - No BOM (byte order mark) </validation_checks>

<validation_result> OUTPUT: { valid: true, errors: [], warnings: [ "File is large (8500 lines) - consider splitting", "Section 'Security' is empty - add placeholder?" ], stats: { total_lines: 542, code_blocks: 42, sections: 15, file_size: "12.5 KB" } } </validation_result>

Step 6: Generate Final Output

Produce the complete, ready-to-save skill file.

<final_output> STRUCTURE: { skill_content: "[Complete markdown string]", file_name: "my-app-api-patterns.md", file_path: ".claude/skills/my-app-api-patterns.md", metadata: { name: "my-app-api-patterns", framework: "spring-boot", version: "3.2.0", skill_type: "api", mode: "analyze", patterns_count: 35, improvements_applied: 8, size_bytes: 12800, line_count: 542 }, validation: { valid: true, ready_to_save: true } } </final_output>

</assembly_flow>

Quality Checks

<quality_assurance> CONTENT_QUALITY: - Examples are clear and relevant - Patterns are well-documented - Anti-patterns are explained - References are included - Quick reference is comprehensive

FORMATTING_QUALITY: - Consistent markdown formatting - Code blocks properly highlighted - Emojis used appropriately - Visual indicators clear (✅ ❌ ⚠️)

COMPLETENESS: - All major sections filled - No TODO or placeholder text - Best practices documented - Examples for key patterns

USABILITY: - Easy to scan and read - Logical section order - Quick reference available - Code examples copy-paste ready </quality_assurance>

Example Output

PROCESS: 1. Generate frontmatter YAML 2. Format template content 3. Add improvement annotations 4. Combine components 5. Validate result

OUTPUT: ```markdown --- name: my-app-api-patterns description: Spring Boot 3.2.0 API patterns for my-app (analyzed from existing codebase) version: 3.2.0 framework: spring-boot created: 2025-12-31 mode: analyze patterns_count: 35 improvements_applied: 8 files_analyzed: 45 globs: - "src//*Controller.java" - "src//Service.java" - "src//*Repository.java" - "src//dto/**/.java" ---

# Spring Boot API Patterns

> Auto-generated skill for my-app
> Framework: Spring Boot 3.2.0
> Generated: 2025-12-31
> Mode: Analyzed from existing codebase

## Improvements Applied

This skill includes 8 improvements to enhance code quality:

Critical:
- Fix SQL injection vulnerability
- Implement centralized error handling

Warnings:
- Add @Transactional to service methods
- Implement pagination with Pageable
- Use Optional for nullable returns

## Framework Configuration

**Detected Setup:**
- Framework: Spring Boot 3.2.0
- Build Tool: Maven
- Language: Java
- Database: PostgreSQL
- ORM: Spring Data JPA

[... rest of content ...]

---

*This skill was generated by Agent OS Add Skill Command*
*Framework: Spring Boot 3.2.0*
*Mode: analyze*
```

Error Handling

<error_protocols> <assembly_failure> LOG: Which component failed PROVIDE: Partial result if possible SUGGEST: Manual intervention </assembly_failure>

<invalid_encoding> FIX: Convert to UTF-8 REMOVE: Invalid characters WARN: About character conversion </invalid_encoding>

<size_exceeded> IF file_size > 500KB: WARN: "Skill file is very large ({size})" SUGGEST: "Consider splitting into multiple skills" ALLOW: User to proceed or modify </size_exceeded> </error_protocols>

Performance Considerations

• Build content incrementally (don't store multiple copies)
• Use string builder pattern for efficiency
• Validate sections as they're added (not at end)
• Stream to file if content is very large

Related Utilities

• @agent-os/workflows/skill/utils/generate-frontmatter.md
• @agent-os/workflows/skill/utils/replace-markers.md
• @agent-os/workflows/skill/utils/parse-template.md
• @agent-os/workflows/skill/interactive/preview-skill.md