user: Give a detailed overview of Skin: syntax, arguments, return values, common patterns.

assistant: # Skin

These rigs implement a flexible system for rigging skin using multiple interacting B-Bone chains.
This is developed as the base for a new modular Rigify face rig.
These are the main ideas of the system:

Generic B-Bone Chain
:   One core idea of the system is that most of the deformation should be implemented
    using a standard powerful B-Bone chain rig. These chains support advanced behavior by
    interacting with other rig components. This is in contrast to having multiple domain-specific rigs
    that each generate their own deform chains.

    The implementation provides two versions of the chain rig: [skin.basic_chain](#skin-basic-chain) merely
    attaches B-Bones to the controls with no automation added to the controls themselves.
    The [skin.stretchy_chain](#skin-stretchy-chain) rig in addition interpolates motion of the end (and an optional middle)
    controls to the other controls of the chain.

Automatic Control Merging
:   The deformation part of the system consists of chains of one or more B-Bones connecting
    control points (nodes). Whenever controls for two chains would completely overlap,
    they are automatically merged.

    For each merged control, one of the chains is selected as the owner, based on heuristic factors
    like parent depth from root, presence of `.T`/`.B` `.L`/`.R` symmetry markers,
    and even alphabetical order as the last resort. This can be overridden by an explicit priority setting
    in cases when it guesses wrong.

    The owner and its parents determine additional automation that is placed on the control.
    As a special case, if a control is merged with its `.T`/`.B` `.L`/`.R` symmetry counterparts
    (detected purely by naming), the automation from all of the symmetry siblings
    of the owner is averaged.

Parent Controllers
:   Rather than simply using the parent meta-rig bone (ORG) as parent for controls and chain mechanisms,
    the new system includes an interface for parent rigs. It explicitly provide parent bones and generate control
    parent automation mechanisms for their child chain controls by inheriting from the appropriate base
    and overriding methods.

    This allows implementing rigs that integrate and manage their child chains in intelligent ways in order
    to add extra automation specific to certain areas. The base skin system includes one simple example
    [skin.transform.basic](#skin-transform-basic) rig, which translates its child control points according to
    its control bone transformation.

Custom Rigging
:   Finally, the new system provides ways to integrate with custom automation directly included in the meta-rig
    via two extra rig components.

    The [skin.anchor](#skin-anchor) rig generates a single control with inherited constraints etc., similar to
    [basic.super_copy](basic.html#rigify-rigs-basic-super-copy). However, it also integrates into the skin system
    as a zero length chain with highest priority. This allows overriding the normal behavior by providing
    a control point under full control of the user, which other chains would automatically attach to.

    The [skin.glue](#skin-glue) rig on the other hand will attach itself to the control that is generated at
    its position (it is an error if there is none). It can be used to read the position of the control
    from custom rigging in the meta-rig, or inject constraints into the control bone. It is possible to
    also detect the control at the tail of the glue bone and use it as target in the constraints,
    thus copying transformation between the controls.