# Skills

Projects are composed of Subjects which are made of Skills (or Skill Groups) and a single skill defines a training unit within the gamification framework. To complete a skill, users may need to perform the same action multiple times - repetition is important for retention after all. A Skill definition specifies how many times a skill has to be performed. Each occurrence is called a Skill Event.

SkillTree Skills Page

To create a skill, navigate to Project -> Subject then click on Skill +, the following skill properties can be specified:

SkillTree Skills Page

Property Explanation
Skill Name Display name of the skill
Skill ID Skill ID that will be used to report skill events
Point Increment Number of points added for each skill event; used in conjunction with the 'Occurrences to Completion' property
Occurrences to Completion Number of successful occurrences to fully accomplish this skill; used in conjunction with the 'Point Increment' property
Time Window Used in conjunction with the 'Max Occurrences Within Window' property; once this Max Occurrences is reached, points will not be incremented until outside of the configured Time Window. When 'Time Window' is disabled skill events are applied immediately."
Max Occurrences Within Window Used in conjunction with the Time Window property; Once this Max Occurrences is reached, points will not be incremented until outside of the configured Time Window.
Self Reporting (Optional) When checked Self Reporting is enabled for this skill. The type of Approval Queue or Honor System can then be selected. When choosing Approval Queue, you may also choose to require users to submit a justification when self-reporting this skill by selecting the 'Justification Required' check box. Please visit Self Reporting to learn more.
Version (Optional) Utilize Skills Versioning to support running multiple versions of client software
Description (Optional) Description of how to perform this skill. The Description property supports markdown.
Help URL/Path (Optional) URL pointing to a help article providing further information about this skill or capability. Please note that this property works in conjunction with the Root Help Url project setting

TIP

To calculate the total points that completion of a particular skill will give a user:

Total Points = Point Increment * Occurrences to Completion

# Copy Skill

To use an existing Skill as a template for a new Skill, you can use the copy skill button button available on a Skill row displayed on the Subject page. This will open a new Skill dialog populated with the details of the selected copy-from Skill. The name and id will be prepended with Copy of which can be changed before the new Skill is saved. Saving this dialog will create a new Skill that falls within the same Subject as the copy-from Skill.

# Best Practices
  • "Repetition is the mother of learning" - use the Occurrences to Completion property in conjunction with the Time Window property to balance between requiring repetition of an action and spacing out that repetition (for example, prevent users from spamming an action in one sitting to max out a Skill by setting a Time Window of 1-8 hours)
  • Help Url - configure the Root Help Url for the project and then enter a path relative to that root. It will then be an easy change if the location of help articles changes.

# Time Window

Time Window is a powerful feature that limits awarding of points to a maximum number of occurrences within the configured time span. This feature provides a balance between requiring repetition of an action and spacing out that repetition.

“Repetition is the mother of learning, the father of action, which makes it the architect of accomplishment.” - Zig Ziglar

When designing a gamification profile, the Time Window must be considered in conjunction with the Occurrences to Completion property. For example, you may want to require 30 occurrences to complete a skill but only up to 5 occurrences within a 24 hour window. This means that it will take a user at a minimum, 6 days to complete this skill. Here are the properties for this hypothetical example:

  • Occurrences to Completion: 30
  • Time Window: 24 hours 0 minutes
  • Max Occurrences Within Window: 5

This is just a fictitious example and values will depend on your gamification needs.

You can also disable the Time Window property of a Skill, which will force each event to be applied immediately (up to Occurrences to Completion). To disable, uncheck the checkbox next to the Time Window property.

# Skills Versioning

Skill versioning is a mechanism that allows the addition of new skills without affecting existing software running with an older skill profile. Versioning is mostly pertinent to the Display Libraries that visualize the skill profile for the version they were declared with.

Here are simple steps to enable Skills Versioning in your application:

  1. When creating a skill, specify a target version (always last deployed version + 1)
    • Version selection can be found on the top-right in the create/edit skills dialogued
  2. When initializing the display component, provide the latest target version for that instance.

Let's walk through a simple scenario to get a better understanding of how Skill Versioning operates.

We have developed software and are releasing a version 0 that integrates skills display and event reporting using the Vue.js library. In the initial release, all of the skills will be created with version 0. The integrated display component will then be initialized with version 0, like this:

<skills-display version="0"/>

This software instance will then get deployed and the skill profile for version 0 is displayed.

Now we are working on the next release which we will label as version 1. Any skill created with version 1 will not be visible in the already deployed software, configured to visualize skills with version 0. The version will need to be updated in the integrated display component to use version 1, like this:

<skills-display version="1"/>

The updated software running the version 1 profile will expose skills declared with both version 0 and version 1. Both versions of software can then run simultaneously and each version will present its own gamification profile.

Please Note

The skills from previous versions are automatically included, so version 3 will contain skills declared with versions 3, 2, 1 and 0

Important

Conveniently, the Skills Dashboard provides a way to view the Client Display for a specific version. Navigate to Project -> User -> Client Display and then select a previous version on the drop-down located above the client display.

Limitations:

  • Deletes are not directly supported. To remove a skill, please perform the following procedure:
    1. update all the client code that is reporting events for the skill that is to be deleted
    2. deploy the version that is not using the skill
    3. delete the skill using the dashboard
  • Edits to skills are not versioned and will be immediately visible to any display with this or earlier versions. This is mostly likely the behavior you want as any edit to a skill is a fix or an improvement.
  • Versioning is only applicable to new skills and doesn't apply to operations done on subjects, badges or other items within the gamificiation framework.

# Manually Add Skill Event

In the event that a Skill is not automatically reported (Skills such as "Attend Presentation" or "Submit a Success Story" are examples of Skill events that might require manual addition), Skill Events can be manually added through the Dashboard.

  1. Locate the Subject that contains the Skill for which you would like to add an event
  2. Select Manage for the located Subject
  3. Locate the Skill and select Manage
    • The Filter box on the top left of the Skills table can be used to quickly locate a particular Skill
  4. Select Add Event from the Navigation menu on the left
  5. Enter the User Id of the user for whom the Skill Event will be added (note that the field supports type-ahead to locate existing users)
  6. Enter a date on which the Skill Event occurred (this will default to today's date)
  7. Select Add

# Incremental Changes

This section explain how various scenarios are handled when skills are modified/removed/added AFTER your application users already earned points, completed skills, achieved levels and obtained badges.

Overall Strategy

  1. Never take away achieved levels and/or earned badges.
  2. Re-calculate users' points when skill's points and/or occurrences are mutated.

SCENARIO: Point Increment is increased ⬆️

Recall that Point Increment is the number of points applied for each skill event. Delta in Point Increment will then be added for any of the already performed skill events. For example if a user performed 2 skill events and Point Increment changed from 5 points to 8 points (delta = 3) then user will be awarded additional 6 (3 * 2) points. If these additional points place a user into the next level then that level will be awarded the next time an event is reported for that user.

SCENARIO: Point Increment is increased ⬇️

Recall that Point Increment is the number of points applied for each skill event. Delta in Point Increment will then be substructed for any of the already performed skill events. For example if a user performed 2 skill events and Point Increment changed from 10 points to 6 points (delta = 4) then 8 (4 * 2) points will be substructed from the user's points.

SCENARIO: Occurrences to Completion is increased ⬆️

Recall that Occurrences to Completion is the number of successful occurrences to fully accomplish a skill. Any users that have already completed the skill based on the lower number of occurrences will now have an opportunity to complete new/additional occurrences and earn those points.

Additional occurrences will cause a completed skill to be worth additional points which in turn may shift the points profile of a user, technically placing certain users outside of their currently achieved level. If so, those users will NOT lose their current level (per our overall strategy) but rather it will take them a bit longer to achieve the next level.

If the increase to occurrences was made for a skill that belongs to a badge, then any user that has already earned that badge will retain the badge achievement.

SCENARIO: Occurrences to Completion is decreased ⬇️

Recall that Occurrences to Completion is the number of successful occurrences to fully accomplish a skill. Points are subtracted for users that already achieved the removed occurrences.

If the removal causes a user to qualify for achievement of the edited skill, then that completed skill is awarded to the user. Subsequently if the completion of that skill completes a badge then the badge is awarded to that user.

Any previously achieved levels and badges are retained even if the removed occurrences contributed to the achievement of those levels and/or badges.

SCENARIO: Skill is removed

For a given user, if this was the last skill to be completed before a badge is achieved then the badge is awarded to that user.

SCENARIO: Skill is added

New skill will equate to extra points which in turn may shift points profile which then may technically place certain users outside of their currently earned level. If so, those users will NOT lose their current level (per our overall strategy) but rather it will take them a bit longer to achieve the next level.

# Same Project Skill Reuse Since skills-service:1.12

In-Project Skill Reuse is a feature that facilitates the reuse of skills within the same project. A skill can be easily reused within another Subject or Skill Group. Reused skills are read-only copies and cannot be mutated. As skill occurrences are reported to the original skill they are also automatically propagated to the reused skills. Changes to the original skill (ex. description, occurrences) are automatically synchronized to all the reused skills as well.

To reuse a skill navigate to the Skills page (Project -> Subject), then select skills to reuse and click on the Action button located on the top-right above the skills' table. Select the Reuse in this Project button to initiate the process.

Reuse skills

Once the skills are reused you will see a REUSED tag next to each skill.

TIP

All the skills under a subject or group can be easily selected for reuse via the Select All button

# Skill occurrences propagation

Please note that when skill occurrences are reported for an original skill, SkillTree checks whether that skill was reused. For every reused instance the occurrence is queued up to be propagated to that reused skills. The queue is handled in an asynchronous manner so there is a small delay before the skill occurrence are reflected in the reused skills.

# Modify skill in the original project

Only the original skill can be updated. After the attributes of the original skill are mutated they are queued up to be propagated to all reused versions of the edited skill. Please note that skill attribute propagation is performed asynchronously, it may take a few moments for changes to appear in all reused skills.

# Self Reporting and Reused Skills

As skill occurrences are reported to the original skill they are also automatically propagated to all reused copies. Generally skill occurrences are not allowed to be reported against a reused skill copy, after all it is meant to be read-only.

The one exception to this restriction is self-reported skills. Self-reported skills can be reported to the original skill OR to any of its reused copies. Regardless of whether it was reported against a reused copy or the natively declared skill, the points are applied to the original AND all of its copies (assuming points are due based on the current configuration and the reported user's prior contributions). When a self-reported skill occurrence is reported to the reused copy then the request is simply routed to the originally-declared skill. From there on the flow is identical to any skill occurrence that is being reported to the original skill and for every reused instance the occurrence is queued up to be propagated to that reused skills. The queue is handled in an asynchronous manner so there is a small delay before the skill occurrence are reflected in the reused skills.

The Self-reporting "I did it" button is visualized for each reused skill in the Skills Display and Progress and Rankings views.

# Other Considerations

  • Skills with dependencies can NOT be reused. Reused skills can NOT be added as a dependency.
  • Reused skills cannot be added to a badge; use the original skill instead
  • Removing the original skill will also delete all of its reused copies

# Move Skills Since skills-service:2.0

Move Skills is a feature that allows project administrators to move skills to other subjects or skill groups within the same project. When skills are moved, users' points are preserved for those skills and level-based achievements are properly re-calculted for both origination and destination subject/group.

TIP

The ability to move skills between subjects gives project administrators gives project administrators the ability to refine their training profile after the initial creation of skills.

To move one or more skills please navigate to the Skills page (Project -> Subject), then select the skills to move and click on the Action button located on the top-right above the skills' table. Select the Move Skills button to initiate the process.

Move skills

TIP

All the skills under a subject or group can be easily selected via the Select All button

Last Updated: 9/29/2022, 4:38:10 PM