Related Pages

Related topics: Installation Guide, Skill Structure & Anatomy

Home - Repository Overview

Introduction

The s4b7-ai/s4b7-ai-skills repository is a skills library designed to extend and automate AI agent capabilities across multiple domains. This repository serves as a central hub for specialized operational skills that enable AI systems (such as Codex, Claude, Gemini, and custom shadow agents) to perform complex tasks including memory management, code refactoring, patent processing, multi-model querying, and engineering intelligence.

The skills are structured as reusable, modular units that can be loaded by AI agents on demand based on contextual triggers. Each skill encapsulates domain-specific workflows, CLI commands, API integrations, and operational patterns.

Sources: skills/write-a-skill/SKILL.md

Related Pages

Related topics: Home - Repository Overview, Skill Dependencies & Metadata

Installation Guide

Overview

This repository (s4b7-ai-skills) is a collection of AI agent skills designed to extend the capabilities of various AI systems including Codex, Claude, Gemini, and local models via Ollama. Each skill is a self-contained module that provides specific functionality, from code refactoring to patent generation.

The installation process involves setting up the skill framework, configuring skill dependencies, and verifying that skills are properly registered and accessible to your AI agents. Skills are defined using YAML frontmatter in SKILL.md files with accompanying scripts and references.

Prerequisites

System Requirements

Required Tools

Before installing skills, ensure the following tools are available:

• Git — Required for cloning repositories and version control operations Sources: skills/shadow-refactor/SKILL.md:25
• pytest/vitest/jest — Test runners for verifying skill functionality Sources: skills/shadow-refactor/SKILL.md:26
• curl — For checking local model availability (Ollama) Sources: skills/shadow-refactor/SKILL.md:23

External Services (Optional)

Installation Steps

Step 1: Clone the Repository

git clone https://github.com/s4b7-ai/s4b7-ai-skills.git
cd s4b7-ai-skills

Step 2: Install Dependencies

Run the installation script to set up the skill framework:

npm install

This will install all required npm dependencies and prepare the skill infrastructure for use. The package.json defines the project dependencies and scripts available for skill management.

Step 3: Configure Skill Paths

Skills are organized in a directory structure that AI agents traverse when loading capabilities. The default skill locations are:

Ensure your AI agent's configuration points to one or more of these directories. For Codex integration, configure ~/.codex/config.toml with the appropriate skill paths.

Step 4: Verify Portability

Check that all skill symlinks and references are valid:

npm run verify:portable

This command validates that skills can be loaded correctly from their configured paths.

Skill Structure

Each skill follows a standardized structure:

skill-name/
├── SKILL.md          # Main skill definition with YAML frontmatter
├── REFERENCE.md      # Detailed reference documentation (optional)
├── scripts/          # Utility scripts (optional)
│   └── helper.js
└── tests/            # Test files (optional)
    └── skill.test.js

SKILL.md Format

Every skill requires a SKILL.md file with this frontmatter structure:

Related Pages

Related topics: Home - Repository Overview, Write A Skill - Authoring Guide, Skill Dependencies & Metadata

Skill Structure & Anatomy

Overview

A Skill is a reusable capability module that encapsulates domain-specific knowledge, workflows, and decision-making patterns for an AI agent. Skills enable agents to perform specialized tasks by providing structured guidance on when and how to apply particular capabilities.

Skills serve as the atomic unit of agentic capability—each skill contains sufficient information for an agent to recognize when it should be invoked and how to execute the associated workflow. The skill system supports a modular architecture where skills can be composed, extended, and shared across different agent contexts.

Core Anatomy of a Skill

Every skill is fundamentally defined by its metadata and operational content. The minimal viable skill consists of YAML frontmatter and a Markdown body that describes the capability.

YAML Frontmatter

The frontmatter uses a standardized schema to ensure parsers and agents can reliably extract skill metadata:

Related Pages

Related topics: Skill Structure & Anatomy, Crystallize - Pattern Extraction

Skill Dependencies & Metadata

Overview

The s4b7-ai-skills repository implements a structured approach to skill documentation that encompasses metadata standards, dependency management, and artifact routing. Each skill follows a consistent SKILL.md template that defines its purpose, trigger conditions, workflows, and integration points with other system components.

The metadata system serves three core purposes: enabling agent-based skill selection through descriptive frontmatter, establishing clear execution workflows with fallback chains, and routing artifacts to appropriate storage locations for persistence and retrieval.

Skill Metadata Structure

Frontmatter Schema

Every skill in the repository begins with YAML frontmatter that defines its identity and selection criteria. The required metadata fields ensure proper agent routing and discovery.

Sources: skills/write-a-skill/SKILL.md:1-20

Description Requirements

The description field is the primary mechanism by which agents decide which skill to load. It must follow a strict two-sentence format:

1. First sentence: States what the skill does
2. Second sentence: Contains the "Use when..." clause specifying trigger conditions

Example of a well-formed description:

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

Sources: skills/write-a-skill/SKILL.md:52-56

The description is surfaced in the system prompt alongside all other installed skills, allowing the agent to pick the relevant skill based on the user's request. This makes the description the single most important metadata element for skill discoverability.

Skill Kinds and Tags

The qmd-memory skill implements a tagging system for memory classification that can be applied to skill metadata:

Tags provide additional dimension to skill metadata, enabling filtering and targeted recall.

Sources: skills/qmd-memory/SKILL.md:45-52

Skill Modes and Command Routing

Mode Architecture

Skills expose multiple operational modes that define different execution paths. The mode system allows a single skill to handle diverse use cases through command-based routing.

graph TD
    A[User Input] --> B{Mode Detection}
    B -->|default| C[Standard Execution]
    B -->|verbose| D[Detailed Diagnostics]
    B -->|json| E[Machine Output]
    B -->|background| F[Autonomous Loop]
    
    C --> G[Primary Handler]
    D --> H[Debug Handler]
    E --> I[Parse Handler]
    F --> J[Background Agent]
    
    G --> K[Result Output]
    H --> K
    I --> K
    J --> K

Sources: skills/codex-latex/SKILL.md:35-48

Mode Reference by Skill

Sources: skills/shadow-engg/SKILL.md:1-30, skills/shadow-refactor/SKILL.md:1-15, skills/shadow-mcp-gadgets/SKILL.md:1-20

Artifact Routing System

Artifact Types

Artifacts are outputs produced during skill execution that require persistent storage. Each skill defines a routing table specifying where artifacts should be stored.

Sources: skills/shadow-refactor/SKILL.md:15-22, skills/shadow-mcp-gadgets/SKILL.md:22-28

Artifact Routing Table Format

Skills implement artifact routing through structured tables in SKILL.md:

| Artifact | Location | Purpose |
|----------|----------|---------|
| Code changes | Project files (inline) | Implementation output |
| Detailed reference | `REFERENCE.md` (skill companion) | Migrations, errors, model notes |
| Original backup | `data/skill-rd/active-split-backups/` | Pre-split archive |

Sources: skills/ai-sdk-core/SKILL.md:28-33

Fallback Chain Architecture

Fallback Principles

Every skill implements a fallback chain that defines recovery behavior when primary execution paths fail. The chain prioritizes available alternatives in order of preference.

graph LR
    A[Primary] --> B[Secondary]
    B --> C[Tertiary]
    C --> D[Last Resort]
    
    style A fill:#90EE90
    style B fill:#FFE4B5
    style C fill:#FFA07A
    style D fill:#FF6B6B

Fallback Chain Examples

ai-sdk-core Fallback Chain:

Sources: skills/ai-sdk-core/SKILL.md:35-42

shadow-engg Fallback Chain:

Sources: skills/shadow-engg/SKILL.md:55-68

skill-surgery-rd Error Handling:

Sources: skills/skill-surgery-rd/SKILL.md:45-55

Skill Dependencies and Interconnections

Crystallization Workflow

The crystallization process creates dependencies between skills by extracting patterns from working sessions into reusable skill definitions.

graph TD
    A[Task Complete] --> B{Should this recur?}
    B -->|yes| C[Review Session]
    B -->|no| D[Done]
    C --> E[Extract Pattern]
    E --> F[Check Scope]
    F --> G{Search Existing Skills}
    G -->|overlap found| H[Update Existing]
    G -->|no overlap| I[Create New Skill]
    H --> J[Log Crystallization]
    I --> J

Sources: skills/crystallize/SKILL.md:55-78

Exploratory-Mode Expansion

When operators request expanded crystallization, the skill performs a broader sweep:

1. Start from the exact thing that was fixed
2. Check nearest adjacent surfaces that could carry the same stale assumption
3. Capture the broader reusable rule

Sources: skills/crystallize/SKILL.md:75-85

Skill Surgery and Dependencies

The skill-surgery-rd skill manages skill dependencies through audit and repair operations. Key operations include:

• Audit: Scan skill directories for stale metadata, circular dependencies, or missing trigger conditions
• Merge: Combine overlapping skills while preserving gotchas from both sources
• Redirect: Route deprecated skill triggers to canonical replacements

Sources: skills/skill-surgery-rd/SKILL.md:1-45

File Reference System

Global File Registry

The codex-context skill maintains a master file reference table for system-wide file access:

Sources: skills/codex-context/SKILL.md:85-98

Key Path Resolution

Sources: skills/codex-context/SKILL.md:35-48

Contract and Constraints

Skill Contracts

Each skill defines a contract specifying operational boundaries:

Sources: skills/shadow-mind/SKILL.md:75-85

Operational Rules

skill-surgery-rd Contract:

• Do not delete skills during exploratory surgery — redirect first
• Do not edit archived history unless surfacing as active trigger problem
• Do not create giant omnibus skills — prefer canonical router plus focused subskills
• Research before invention — never crystallize stale version numbers without freshness note

Sources: skills/skill-surgery-rd/SKILL.md:57-70

shadow-engg Contract:

• Never modify production config without operator confirmation
• Report all changes with before/after diff
• Preserve existing configurations with backup

Sources: skills/shadow-engg/SKILL.md:125-130

Integration with MCP Gadgets

Gadget Mode Routing

The shadow-mcp-gadgets skill routes commands to specialized tools based on trigger phrases:

Sources: skills/shadow-mcp-gadgets/SKILL.md:8-18

Recall Scoring System

The shadow-mind skill implements confidence-based recall for skill metadata:

Always label recall confidence. Never present inferred as confirmed.

Sources: skills/shadow-mind/SKILL.md:55-65

Review Checklist

After drafting or updating skill metadata, verify:

• [ ] Description includes "Use when..." trigger clause
• [ ] SKILL.md under 100 lines (split if exceeded)
• [ ] No time-sensitive info that will become stale
• [ ] Consistent terminology with adjacent skills
• [ ] Concrete examples included
• [ ] References one level deep only

Sources: skills/write-a-skill/SKILL.md:95-102

Related Pages

Related topics: AI SDK Core - Vercel Integration, Agent Crystallization Protocol

LangGraph Agent Development

Overview

LangGraph Agent Development provides a framework for building stateful, multi-agent applications using LangGraph's graph-based architecture. It enables developers to create agents that maintain context across interactions, coordinate multiple sub-agents, and handle complex workflow orchestration through explicit state management and conditional routing.

LangGraph extends the concept of LLM chains by introducing nodes (agents/tools) and edges (transitions) within a directed graph structure, allowing for more sophisticated agentic behaviors than linear chain implementations.

Core Concepts

Graph Architecture

LangGraph applications are built as stateful graphs composed of nodes and edges:

State Management

State in LangGraph is typically a TypedDict or Pydantic model that accumulates data as it flows through the graph:

from typing import TypedDict
from typing_extensions import Annotated
import operator

class AgentState(TypedDict):
    messages: Annotated[list, operator.add]
    context: dict
    next_action: str

The Annotated type with operator.add enables message accumulation, where each node appends to the messages list rather than replacing it.

Workflow Patterns

Basic Agent Loop

graph TD
    A[User Input] --> B[LLM Decision Node]
    B --> C{Should Respond?}
    C -->|Yes| D[Return to User]
    C -->|No| E{Should Use Tool?}
    E -->|Yes| F[Execute Tool]
    E -->|No| G[Continue to Next Node]
    F --> H[Update State]
    H --> B
    G --> I[End or Next Agent]
    I --> D

Multi-Agent Orchestration

For complex tasks, LangGraph enables hierarchical agent architectures:

Advanced Patterns

Human-in-the-Loop

Integrating human feedback into agent execution:

def human_review_node(state: AgentState) -> AgentState:
    user_input = interrupt("Awaiting human review...")
    return {"feedback": user_input}

The interrupt function pauses execution and yields control to external systems (UIs, APIs) for human approval before resuming.

Memory Persistence

LangGraph supports checkpointing for long-running conversations:

from langgraph.checkpoint.sqlite import SqliteSaver

checkpointer = SqliteSaver.from_conn_string(":memory:")
graph = compileprompt | model | parser, checkpointer=checkpointer)

Checkpoints enable:

• Conversation resumption after interruptions
• Branching for exploration
• Audit trails of agent decisions

Tool Integration

Tools are defined as functions and integrated into the graph:

from langchain_core.tools import tool

@tool
def search_codebase(query: str) -> str:
    """Search the codebase for relevant files."""
    # Implementation
    return results

tools = [search_codebase]

API Reference

Compiling the Graph

from langgraph.graph import StateGraph, END

workflow = StateGraph(AgentState)
workflow.add_node("agent", agent_node)
workflow.add_node("tools", tool_node)

workflow.set_entry_point("agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "agent",
        "end": END,
    }
)

app = workflow.compile()

Key Parameters

Best Practices

Error Handling

Implement retry logic and fallbacks within nodes:

def robust_agent_node(state: AgentState) -> AgentState:
    max_retries = 3
    for attempt in range(max_retries):
        try:
            result = risky_operation(state)
            return {"result": result, "status": "success"}
        except Exception as e:
            if attempt == max_retries - 1:
                return {"error": str(e), "status": "failed"}
            continue

State Optimization

Minimize state size to improve performance:

• Use references (IDs) instead of full objects where possible
• Implement state pruning at node boundaries
• Separate ephemeral vs. persistent state concerns

Testing Strategies

Integration with s4b7-ai-skills

The LangGraph Agent Development skill follows the repository's skill template structure:

• Quick Start: Minimal working example for agent initialization
• Workflows: Step-by-step processes with checklists
• Advanced Features: Referenced in companion files for specialized patterns

Sources: skills/write-a-skill/SKILL.md

Related Skills

Conclusion

LangGraph Agent Development provides the architectural foundation for building sophisticated, stateful agent systems. By modeling agents as nodes in a graph with explicit state management and conditional routing, developers can create predictable, debuggable, and scalable agentic applications that handle complex multi-step workflows effectively.

Related Pages

Related topics: LangGraph Agent Development

AI SDK Core - Vercel Integration

Overview

The AI SDK Core skill provides a comprehensive toolkit for building backend AI applications using the Vercel AI SDK. It supports both stable v5 and v6 beta releases, offering capabilities for text generation, streaming, structured output, and agent-based workflows.

This skill targets developers implementing AI-powered backend routes, migrating between SDK versions, troubleshooting runtime errors, or integrating with latest AI models from OpenAI, Anthropic, and Google.

Sources: skills/ai-sdk-core/SKILL.md

Skill Metadata

Sources: skills/ai-sdk-core/SKILL.md

Supported Capabilities

Core Functions

Advanced Features (v6 Beta)

Sources: skills/ai-sdk-core/SKILL.md

Quick Start Workflow

graph TD
    A[Task Request] --> B{Identify Task Type}
    B -->|New Route| C[Core Functions]
    B -->|Agent/Tool Loop| D[v6 Agent Abstraction]
    B -->|Migration| E[Breaking Change Checklist]
    B -->|Error Fix| F[Error Cookbook]
    C --> G[Install Packages]
    D --> G
    E --> H[Follow Migration Guide]
    F --> I[Apply Recipe]
    G --> J[Implement & Test]
    H --> J
    I --> J

Installation

npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google zod

# Beta lane when explicitly needed:
npm install ai@beta @ai-sdk/openai@beta @ai-sdk/react@beta

Sources: skills/ai-sdk-core/SKILL.md

Task Routing

Sources: skills/ai-sdk-core/SKILL.md

v4 to v5 Breaking Changes

The migration from v4 to v5 introduces several breaking changes that require code updates.

Sources: skills/ai-sdk-core/references/v5-breaking-changes.md

Message Types Renaming

Before (v4):

import { CoreMessage, convertToCoreMessages } from 'ai';

const messages: CoreMessage[] = [
  { role: 'user', content: 'Hello' },
];

const converted = convertToCoreMessages(uiMessages);

After (v5):

import { ModelMessage, convertToModelMessages } from 'ai';

const messages: ModelMessage[] = [
  { role: 'user', content: 'Hello' },
];

const converted = convertToModelMessages(uiMessages);

Sources: skills/ai-sdk-core/references/v5-breaking-changes.md

Tool Error Handling

Before (v4):

import { ToolExecutionError } from 'ai';

const tools = {
  risky: {
    execute: async (args) => {
      throw new ToolExecutionError({
        message: 'API failed',
        cause: originalError,
      });
    },
  },
};

After (v5):

const tools = {
  risky: tool({
    execute: async (input) => {
      throw new Error('API failed');
    },
  }),
};

Sources: skills/ai-sdk-core/references/v5-breaking-changes.md

Error Solutions

The skill includes a cookbook with 12+ error solutions covering common runtime issues.

Sources: skills/ai-sdk-core/SKILL.md

Common Decision Points

Sources: skills/ai-sdk-core/SKILL.md

Provider Integration

Supported Providers

Sources: skills/ai-sdk-core/SKILL.md

Cloudflare Workers Special Handling

Cloudflare Workers have strict startup budgets. When implementing AI SDK in Workers environments:

1. Use lazy imports for AI SDK packages
2. Defer model initialization until first request
3. Apply the Workers-specific fix from REFERENCE.md

Sources: skills/ai-sdk-core/SKILL.md

Fallback Chain

When primary references are unavailable or stale, use this fallback sequence:

graph LR
    A[Request] --> B{REFERENCE.md Available?}
    B -->|Yes| C[Use Detailed Reference]
    B -->|No| D{Web Search Available?}
    D -->|Yes| E[Search Official Docs]
    D -->|No| F{npm view Available?}
    F -->|Yes| G[Check Latest Version]
    F -->|No| H[Use Stable v5 Default]

Sources: skills/ai-sdk-core/SKILL.md

Artifact Routing

Sources: skills/ai-sdk-core/SKILL.md

Reference File Structure

skills/ai-sdk-core/
├── SKILL.md                          # Main skill file
├── REFERENCE.md                      # Detailed reference
├── references/
│   ├── v5-breaking-changes.md       # v4→v5 migration guide
│   ├── top-errors.md                 # Error cookbook
│   ├── providers-quickstart.md       # Provider setup
│   └── links-to-official-docs.md     # External resources
├── templates/
│   ├── generate-text-basic.ts
│   ├── stream-text-chat.ts
│   └── generate-object-zod.ts
└── data/
    └── skill-rd/
        └── active-split-backups/     # Archive versions

Sources: skills/ai-sdk-core/SKILL.md

External Resources

Sources: skills/ai-sdk-core/references/links-to-official-docs.md

Complementary Skills

Sources: skills/ai-sdk-core/references/links-to-official-docs.md

Keywords

The skill is triggered by these terms:

• ai sdk core, vercel ai sdk, ai sdk v5, ai sdk v6 beta, ai sdk 6
• agent abstraction, tool approval, reranking support
• human in the loop, generateText, streamText
• generateObject, streamObject, ai sdk node, ai sdk server
• zod ai schema, ai schema validation, ai tool calling
• ai agent class, openai sdk, anthropic sdk

Sources: skills/ai-sdk-core/SKILL.md

Related Pages

Related topics: Crystallize - Pattern Extraction, Write A Skill - Authoring Guide

Agent Crystallization Protocol

The Agent Crystallization Protocol is a systematic methodology for transforming implicit knowledge, problem-solving patterns, and learned insights from agent sessions into explicit, reusable, and discoverable skills. It serves as the intentional counterpart to automated pattern detection (SP-006), enabling agents to capture knowledge that emerges from reasoning and understanding rather than mere tool usage observation.

Purpose and Scope

The crystallization protocol addresses a fundamental challenge in agentic systems: knowledge decay and inability to reuse past solutions. When an agent successfully solves a complex problem, that solution remains trapped in session memory unless explicitly captured. The crystallization protocol provides the workflow, standards, and tooling to extract these patterns into durable skills that future sessions can leverage.

Primary Objectives:

Scope Boundaries:

The protocol distinguishes between what should be crystallized and what should not:

• Crystallize: Novel problem-solving approaches, reusable workflows, decision heuristics, gotchas discovered through reasoning, cross-domain patterns
• Do Not Crystallize: Time-sensitive information (pricing, API versions), obvious operations derivable from codebase inspection, highly specific one-off solutions Sources: skills/crystallize/SKILL.md

Architecture Overview

The crystallization system operates as a closed loop between session execution and skill repository management:

graph TD
    A[Agent Session] -->|Completes Task| B{Should this recur?}
    B -->|Yes| C[Review Session]
    B -->|No| Z[Session Ends]
    C --> D[Extract Pattern]
    D --> E[Check Scope]
    E --> F{Skill overlap found?}
    F -->|Yes| G[Update Existing Skill]
    F -->|No| H[Create New Skill]
    G --> I[Log Crystallization Metadata]
    H --> I
    I --> J[Skill Repository]
    J -->|Future Sessions| A

Relationship to SP-006

The protocol intentionally complements SP-006 (Latent Skill Observer), which automatically detects patterns from tool call sequences:

Both mechanisms feed into the same skill namespace, ensuring that automatically detected and intentionally crystallized knowledge coexist and reinforce each other. Sources: skills/crystallize/SKILL.md

Crystallization Workflow

The standard crystallization workflow proceeds through seven discrete phases:

Phase 1: Review Session

Before extracting any pattern, the agent must thoroughly understand what was accomplished:

Review Questions:

• What was the original task?
• What problem was solved?
• What was learned that wasn't known before?
• What steps would be repeated identically in a similar future task?

This phase establishes the context necessary to determine whether crystallization is warranted and what form it should take. Sources: skills/crystallize/SKILL.md

Phase 2: Pattern Extraction

The core analytical phase where implicit knowledge becomes explicit. Extract four categories of information:

Key Steps: The minimal sequence of actions that produces the desired result. Include only essential steps; omit accidental details from the specific session.

Heuristics: The judgment calls required during execution. These are the "rule of thumb" decisions that determine success—where did the agent need to choose between approaches, and what guided that choice?

Gotchas: What went wrong or nearly went wrong. Include assumptions that failed, edge cases that weren't anticipated, and common mistakes in the domain.

Decision Points: Where the agent chose between competing approaches. Document both the choice made and the determining factors. Sources: skills/crystallize/SKILL.md

Phase 3: Exploratory Mode Expansion

When the operator requests deeper crystallization or explicitly invokes --exploratory-mode, the protocol expands one "ring" outward from the immediate fix:

graph LR
    A[Exact Fix] --> B[Adjacent Surface 1]
    A --> C[Adjacent Surface 2]
    A --> D[Adjacent Surface 3]
    B --> E{Same Stale Assumption?}
    C --> E
    D --> E
    E -->|Yes| F[Capture Broader Pattern]
    E -->|No| G[Leave Untouched]

Exploratory Sweep Process:

1. Identify the exact element that was fixed
2. Check the nearest adjacent surfaces that could carry the same stale assumption
3. Evaluate whether the extracted pattern applies broadly or is specific to one surface
4. Capture the broader reusable rule if the pattern holds across surfaces
5. Explicitly note which adjacent surfaces were checked and intentionally left untouched Sources: skills/crystallize/SKILL.md

Phase 4: Scope Determination

Before creating or updating skills, determine the appropriate scope:

Scope determination prevents the creation of skills that are either too narrow (duplicating existing capabilities) or too broad (mixing concerns that should be separate). Sources: skills/crystallize/SKILL.md

Phase 5: Deduplication Search

Before creating a new skill, search for existing skills that may overlap:

Search Targets:

• Skills with similar triggers or descriptions
• Skills in adjacent domains that might subsume the new pattern
• Deprecated skills that might redirect to canonical locations

Decision Matrix:

If a related skill exists, add the new pattern as a new section or extend the existing workflow while preserving the skill's existing structure. Sources: skills/crystallize/SKILL.md

Phase 6: Skill Creation or Update

#### Creating a New Skill

Follow the standardized skill structure:

~/.agents/skills/<skill-name>/
├── SKILL.md           # Primary skill definition
├── REFERENCE.md       # Detailed reference (optional)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

#### Updating an Existing Skill

When extending an existing skill:

1. Add new sections without modifying existing content structure
2. Extend workflows only when the new pattern logically belongs
3. Preserve all existing gotchas and decision points
4. Update the "Crystallized From" metadata

#### SKILL.md Template Structure

Related Pages

Related topics: Crystallize - Pattern Extraction, Skill Surgery R&D, Skill Structure & Anatomy

Write A Skill - Authoring Guide

Overview

The Write A Skill authoring guide provides a standardized template and methodology for creating reusable agent capabilities within the skills ecosystem. Skills are self-contained units of functionality that agents can load and invoke based on context, enabling modular and maintainable agent behavior. Sources: skills/write-a-skill/SKILL.md:1-15

This guide defines the canonical structure for skill development, including metadata requirements, workflow documentation patterns, and organizational best practices. The authoring framework ensures consistency across all skills while maintaining flexibility for diverse use cases.

Skill Anatomy

Core Components

Every skill follows a standardized directory structure to ensure predictability and discoverability:

skill-name/
├── SKILL.md          # Primary documentation and entry point
├── REFERENCE.md      # Advanced usage (optional)
├── docs/             # Additional documentation (if needed)
└── scripts/          # Utility scripts (if needed)
    └── helper.js

Sources: skills/write-a-skill/SKILL.md:1-7

SKILL.md Template

The SKILL.md file serves as the primary interface for skill discovery and usage. It must follow this structure:

Related Pages

Related topics: Agent Crystallization Protocol, Write A Skill - Authoring Guide, Skill Surgery R&D

Crystallize - Pattern Extraction

Overview

Crystallize is a systematic skill for extracting reusable patterns from completed task sessions and capturing them as persistent, reusable skills. It transforms tacit knowledge gained during problem-solving into explicit, structured documentation that can be leveraged in future tasks.

The Crystallize skill serves as a complementary mechanism to SP-006 (latent skill observer), which automatically detects patterns from tool call sequences. While SP-006 observes tool usage, Crystallize adds intentional extraction from reasoning—patterns that emerge from understanding the problem domain, not just from observing execution traces.

Core Purpose

The primary objectives of Crystallize are:

Workflow

The Crystallize process follows a structured decision tree that determines whether a pattern warrants extraction and how it should be documented.

graph TD
    A[Task Complete] --> B{Should this recur?}
    B -->|Yes| C[Review Session]
    B -->|No| Z[Done]
    C --> D[Extract Pattern]
    D --> E[Check Scope]
    E --> F[Search Existing Skills]
    F -->|Overlap Found| G[Update Existing]
    F -->|No Overlap| H[Create New Skill]
    G --> I[Log Crystallization]
    H --> I
    I --> Z

Phase 1: Review

The review phase establishes context by answering fundamental questions about the completed task:

• What was the task? — Define the original objective
• What problem was solved? — Identify the core challenge
• What did I learn? — Extract the key insight or technique
• What steps would I repeat next time? — Determine the reusable sequence

Sources: skills/crystallize/SKILL.md:1-20

Phase 2: Pattern Extraction

This phase identifies the reusable elements from the completed session:

Phase 3: Scope Check

Determine whether the pattern is:

• General — Applicable across multiple domains or tasks
• Domain-Specific — Limited to a particular technology, framework, or context

Phase 4: Deduplication

Search existing skills to prevent overlap:

1. Check for similar trigger phrases in other skill descriptions
2. Evaluate whether the pattern extends or supersedes existing skills
3. Make the create-vs-update decision

Phase 5: Create or Update Skill

#### Creating a New Skill

Place skills in the appropriate location based on scope:

#### Updating an Existing Skill

When overlap is found, add the new pattern as a new section or extend the existing workflow. Preserve the skill's existing structure while integrating the new information.

Phase 6: Log the Crystallization

Record metadata at the bottom of the skill under ## Crystallized From:

## Crystallized From
- Session: [date/context]
- Original task: [what was being solved]
- Pattern extracted: [what pattern was extracted]
- Exploratory mode notes: [adjacent surfaces checked and left untouched]

Crystallization Modes

The Crystallize skill supports multiple operational modes to handle different crystallization scenarios:

Exploratory-Mode Expansion

When the operator requests exploratory mode, do not stop at the first local fix. Expand one ring outward using this sweep:

1. Start from the exact thing that was fixed
2. Check the nearest adjacent surfaces that could carry the same stale assumption
3. Capture the broader reusable rule

Artifact Routing

All crystallization artifacts are routed to specific locations based on their type and purpose:

SKILL.md Template

When creating a new crystallized skill, use this structure:

# Skill Name

One-line description. Use when [trigger phrases].

## When to Use
- [trigger 1]
- [trigger 2]
- [trigger 3]

## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Key Decisions
- [Decision point 1]: [default choice + why]
- [Decision point 2]: [default choice + why]

## Gotchas
- [Common mistake 1]
- [Common mistake 2]

## Crystallized From
- Session: [date/context]
- Original task: [what was being solved]

Fallback Chain

When primary methods are unavailable, Crystallize follows a fallback chain:

1. Primary: Full workflow — review → extract → scope → deduplicate → create/update
2. Quick mode unavailable: Capture to minimal stub
3. Existing skills check fails: Create new skill without deduplication check
4. Logging unavailable: Skip optional crystallization log entry

Relationship with SP-006

Both mechanisms feed the same skill namespace, meaning patterns captured via Crystallize become available alongside automatically detected patterns from SP-006.

Best Practices

1. Capture decision rationale — Not just what was done, but why it was chosen over alternatives
2. Include failure modes — Document what assumptions failed and what went wrong
3. Be specific with triggers — Include exact phrases that should activate the skill
4. Maintain minimal examples — Keep the workflow concise; detailed reference material can be separate files
5. Log the crystallization context — Future maintainers need to understand the original problem

Related Pages

Related topics: Crystallize - Pattern Extraction, Write A Skill - Authoring Guide

Skill Surgery R&D

Overview

Skill Surgery R&D is a specialized operational capability within the shadow-verse ecosystem designed to audit, maintain, and optimize the skill garden. It provides structured workflows for analyzing skill inventory, detecting overlaps, identifying gaps, and performing surgical interventions on skill files.

Purpose: The skill serves as a meta-level operations layer that ensures the skill ecosystem remains healthy, non-redundant, and properly aligned with user intents.

Scope: Skill Surgery R&D operates across the entire skill inventory, examining both structural integrity and semantic coverage of installed skills.

Sources: skills/skill-surgery-rd/SKILL.md

Architecture

Skill Surgery R&D Structure

skill-surgery-rd/
├── SKILL.md                              (main skill definition)
├── scripts/
│   ├── audit-skills.mjs                  (inventory scanner)
│   └── redirect-deprecated-skill.mjs     (redirect migration)
├── data/skill-rd/
│   ├── skill-inventory.json              (machine-readable catalog)
│   └── semantic-duplicate-clusters.json   (overlap analysis)
└── ShadowArchive/80-reports/
    └── skill-rd-YYYY-MM-DD.md            (surgery reports)

Skill Classification Taxonomy

The system classifies skills into the following categories for surgical planning:

Sources: skills/skill-surgery-rd/SKILL.md

Operational Modes

Skill Surgery R&D supports multiple operational modes for different use cases:

Sources: skills/skill-surgery-rd/SKILL.md

Surgical Operations

Surgery Decision Workflow

graph TD
    A[Audit Skill Garden] --> B{Classification}
    B -->|trigger-deprecated| C[Redirect Operation]
    B -->|trigger-repair| D[Rewrite Frontmatter]
    B -->|overlap| E[Merge Operation]
    B -->|stale-lane| F[Trim + Deprecate]
    B -->|runtime-gap| G[Create Scripts]
    C --> H[Validate Changes]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[Report Outcomes]

Surgery Types

#### 1. Redirect

Redirects a deprecated skill to its canonical replacement while preserving migration guidance.

# Redirect a deprecated skill
node /Users/sdluffy/.agents/skills/skill-surgery-rd/scripts/redirect-deprecated-skill.mjs \
  --mapping=data/skill-rd/map.json

Validation criteria:

• Confirm target canonical skill exists
• Preserve migration notes in redirect
• Verify no active triggers point to deprecated path

#### 2. Trigger Repair

Rewrites the frontmatter description with concrete "Use when..." triggers.

Before:

Doramagic Pitfall Log

Doramagic extracted 7 source-linked risk signals. Review them before installing or handing real data to the project.

1. Project risk: Project risk needs validation

• Severity: medium
• Finding: Project risk is backed by a source signal: Project risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.

3. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing

4. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium

6. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown

7. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using s4b7-ai-skills with real data or production workflows.

• Project risk needs validation - GitHub / issue