> ## Documentation Index
> Fetch the complete documentation index at: https://thehyperstack.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Skills
> Link your skill tags to ESCO skills or to your own skill list. Each badge then points to a clear definition of the skill.
A group's **skill and knowledge tags** are free text. "Data analysis" at one issuer and "Data analytics" at another are two different words, and no system can tell what they mean.
You can now **link** a tag to a skill in a standard list. The tag keeps its own text. The link adds the skill's official name, description, code and web address. You can link to:
* **ESCO**, the European Commission's list of skills, or
* **your own skill list**, such as your competency framework with your own codes.
What a link gives you:
* The **credential page** marks linked tags. A click opens a short panel about the skill.
* The **Open Badges** 2.0 and 3.0 data of each credential carries the skill as an `alignment`, the standard field for this.
* Each skill of your own list gets a **public skill page**, unless it has a web page of its own.
> [!NOTE]
>
> Skills are on every plan: ESCO skills and your own skill lists. You need the **Credential issuer** or **Administrator** role to link skills, and an administrator to manage your own skill lists.
## What is ESCO
[ESCO](https://esco.ec.europa.eu/) is the European Commission's free list of skills, in many languages. It has about 13,900 skills, each with a name, a description and a fixed web address. Hyperstack uses ESCO version 1.2.1.
Skill names and descriptions come in English, Arabic, German, Spanish, French, Irish, Italian and Portuguese. In Hyperstack's other languages, they show in English.
When you link a tag to an ESCO skill, the badge carries a standard skill with a stable link. Employers and other systems can read it in the badge's data, the same way for every issuer.
Skills from ESCO, European Commission. This service uses the ESCO classification of the European Commission.
## Link a tag when you add it
**1. Open the group**
Go to **Credential Groups** and click the group, or create a new one.
**2. Open Marketing**
Under **More settings**, click **Marketing**. The field is **Skill and knowledge tags**.
**3. Type two or more letters**
A list opens under the field:
* The first row is **Add "…" as a tag**. Press Enter to add your text as a plain tag, as before.
* Under **ESCO** are up to 6 ESCO skills, each with its description.
* Under each of your own lists are up to 3 of its skills, with their codes.
**4. Pick a skill**
Click a skill, or move to it with the arrow keys and press Enter. It is added as a linked tag. A skill that is already in the field shows **Added**.
**5. Save the group**
Click **Update group** or **Create group**. Links are saved only with the group.
A linked tag has a link icon and a small mark: **ESCO**, or the code of your own skill. A skill of your own list without a code shows the icon alone. Plain tags look as before.
The closed **Marketing** block counts the links, for example **6 skill tags · 3 linked**.
An ESCO tag uses the ESCO name in the group's language, when ESCO has that language. Otherwise it uses the English name. A tag from your own list uses the name as you typed it.
## Link a tag you already have
**1. Click the tag**
Its menu opens.
**2. Click Link to a skill…**
The search opens with the tag's text in it. Change the text to search for something else.
**3. Choose a skill and click Link skill**
The tag keeps its own text. Only the link is added.
**4. Save the group**
### The menu of a linked tag
Click a linked tag to see its skill and where it comes from.
* **Open in ESCO** or **Open skill page**: opens the skill's page in a new tab.
* **Replace link…**: links the tag to another skill.
* **Unlink**: the tag becomes plain. Click **Undo** in the message to take it back.
* **Remove**: removes the tag and its link, like **×**.
Changes count only when you save the group.
If you remove a tag, or change its text, its link goes too.
## Match my tags
Use **Match my tags** to link many plain tags at once. The button shows when the field has at least one plain tag.
**1. Click Match my tags**
Hyperstack looks for an ESCO skill for each plain tag. Each row shows the tag, the skill it found, the skill's description and how it matched:
* **Same name**: the ESCO skill has the same name as your tag.
* **Other name**: your tag is another name of the ESCO skill.
* **No match.**: nothing found. Click **Search…** to look for a skill yourself.
**2. Accept or skip each row**
Click **Accept** to link the tag, or **Skip** to leave it plain. **Undo** takes back your choice. **Accept all same-name matches** accepts only the **Same name** rows.
Nothing links until you accept it. Read the description first: a match by name can still be the wrong skill.
**3. Click Link N tags**
The links go into the form.
**4. Save the group**
## Your own skill lists
Keep your own competency list under **Settings → Skills**. **Skills** is under **Workspace** in the settings menu. Groups pick from your lists next to ESCO.
Each list is a tab, with its number of active skills. The table shows each skill's:
* **Name** and description.
* **Code**.
* **Groups**: how many groups use the skill.
* **Page**: the skill's own web page, or **Our page** when Hyperstack makes one. See [The public skill page](#the-public-skill-page).
Use **Search skills** to find a skill by name, code or description. Use **Status** to show **Active**, **Retired** or **All** skills.
### Add a skill
**1. Click New skill**
With no list yet, the window first asks for the list's name. The list name shows on badges as the framework, for example "Acme competencies".
**2. Fill in the skill**
* **List**: shows when you have more than one list.
* **Name**: required.
* **Code (optional)**: your own code. Badges carry it as the skill code. Each code can be in a list once.
* **Description (optional)**: what the skill means.
* **Web page (optional)**: the skill's page on your own site. It must start with `https://`. Leave it empty and Hyperstack makes a page for the skill.
**3. Click Add skill**
To edit a skill, click its row. When groups use the skill, the window says how many. Their tags keep their own text, and their badges show the new name and description at once.
### Lists
* **New list**: adds a list. A list name can be used once.
* **⋯** next to the tabs: **Rename list**, or **Delete list**. You can delete a list only when no group has used its skills.
### Retire or delete a skill
Click **⋮** on the skill's row.
* **Retire skill**: the skill leaves the list you pick from in groups. Groups that use it keep it, and their badges still point to it. A retired tag shows **Retired** in the group form. To bring the skill back, click **Restore**.
* **Delete skill**: only for a skill that no group has ever used. It is deleted for good.
A skill that a group has ever used can only be retired, never deleted. So issued badges never point to a skill that is gone.
**Copy page link** copies the address of the skill's public page.
### Import skills from a CSV file
**1. Click Import CSV**
**2. Choose the list**
Under **Add to list**, choose a list, or **New list…**.
**3. Choose your CSV file**
Up to 1 MB and 1,000 skills. Click **Download a sample CSV** for a file to start from.
**4. Check the preview**
Each row shows **New**, **Update** or its problem. Rows with problems are listed first.
**5. Click Import N skills**
The window closes and the list opens.
The file needs a header row. Only `name` is needed. The columns can be in any order.
| Column | What to put in it |
| - | - |
| `name` | The skill's name. Up to 200 characters. |
| `code` | Your code. Up to 64 characters. Each code once in the file. |
| `description` | What the skill means. Up to 1,000 characters. |
| `url` | The skill's own web page. It must start with `https://`. |
The sample file:
```csv theme={null}
name,code,description,url
Spreadsheet modelling,ACM-12,Builds models in a spreadsheet to test plans and costs.,
Contract law basics,ACM-13,,https://example.com/skills/contract-law
```
How rows match the skills you have:
* A row with a code updates the skill with that code in the list.
* A row without a code updates the skill with the same name. Upper and lower case don't matter.
* Any other row adds a new skill.
* A retired skill that matches is updated and stays retired.
Rows with problems are skipped. Fix them in your file and import it again. Save the file as CSV (UTF-8).
## What recipients and verifiers see
### The credential page
Linked tags show the link icon and their mark: **ESCO** or your code. Plain tags look as before. A click on a linked tag opens a panel under the tags.
For an ESCO skill, the panel shows:
* the ESCO name of the skill and **ESCO skill**,
* its description,
* **View in ESCO**, which opens the skill on the ESCO site,
* **Skills from ESCO, European Commission.**
For a skill of your own list, the panel shows the skill's name, the list name, the description, the **Code**, **View skill** and **From** *your organization's* **own skill list.**
The tag keeps your text. The panel shows the skill's own name, so the two can differ.
### Open Badges
The [Open Badges](https://thehyperstack.com/docs/api-guide/open-badges.md) 2.0 and 3.0 data of each credential has an `alignment` list, with one entry per linked skill, in the order of your tags:
| Field | What it holds |
| - | - |
| `targetName` | The skill's name |
| `targetUrl` | The ESCO address of the skill, your skill's web page, or its public skill page |
| `targetDescription` | The description, when there is one |
| `targetFramework` | `ESCO`, or your list's name |
| `targetCode` | The ESCO code of the skill, or your code, when there is one |
* `tags` stays as before, with all your tags.
* A group without linked tags has no `alignment`. Its data stays exactly as before.
* The data is made each time someone opens it. So a new link, or an edit of your skill, shows in every credential of the group at once, also in credentials you issued before.
### What does not change
* The certificate and badge images, the PDF, the credential ID and the blockchain record.
* The transcript, your showcase page and the earners directory. They show the tags as before.
* The wallet, emails and Google Wallet passes.
* **Add to LinkedIn Profile**. LinkedIn does not take skills from it.
## The public skill page
Each skill of your own list without a web page of its own gets a public page:
`https://hyperstack.id//skills/`
Badges link to this page in `targetUrl`. **View skill** on the credential page opens it too. To get the link, click **Copy page link** in the skill's menu, or open it from **Our page** in the table.
The page shows:
* the skill's name, your organization's name, the list, the code and the status,
* **About this skill**, when the skill has a description,
* **Credentials with this skill**: up to 24 of your groups that use the skill and are listed publicly. Each links to its program page.
It never shows recipients' names or how many people earned a credential. Groups that are not listed publicly don't show.
* **A retired skill** keeps its page, marked **Retired**, so badges that point to it keep working.
* **A skill with its own web page** has no page here. Its address sends visitors to your web page, so badges issued before you added the web page still work.
* **On your own domain**, the page also opens at `/skills/`. Badges always use the `hyperstack.id` address, so they keep working if your domain changes.
## Languages
* **In the Studio**, the search finds skills in the Studio's language and in English. ESCO names show in the Studio's language when ESCO has it, else in English.
* **On the credential page and in Open Badges**, ESCO names and descriptions are in the credential's language, or else the group's language, when ESCO has it. Otherwise they are in English.
* **Your own skills** show as you typed them, in every language.
* **Tags keep their text** in every language. See [Credential Languages](https://thehyperstack.com/docs/tutorials/credential-setup/credential-languages.md).
ESCO has skill names in English, Arabic, German, Spanish, French, Irish, Italian and Portuguese. In Hindi, Korean, Russian, Swahili, Tamil and Chinese, the search shows **ESCO · in English**, and skills show in English. ESCO's Spanish and Portuguese are the European forms. Hyperstack shows them as ESCO writes them.
## Outdated ESCO skills
ESCO publishes a new version from time to time. If a new version drops a skill that you linked, the tag shows a warning sign in the group form, and its menu says **Outdated in ESCO** with the version. Badges still carry the skill. Click **Replace link…** to link a current skill if you want.
The credential page shows the skill as before.
## Audit logs
Changes to links and skill lists show in the [audit logs](https://thehyperstack.com/docs/tutorials/advanced-setup/audit-logs.md): links, unlinks, accepted matches, and skills added, edited, retired, restored or imported.
## Use the API or an AI assistant
* The [API](https://thehyperstack.com/docs/api-guide/view-credential-group.md) returns `skills` with a group that has linked tags: each tag's name, framework, code and web address. `tags` stays as before. Groups can be created and updated with `skills` too.
* `GET https://api.thehyperstack.com/v1/skills?q=` searches ESCO and your own lists, and returns up to 20 skills.
* The [MCP server](https://thehyperstack.com/docs/api-guide/mcp-server.md) has a `search_skills` tool. `create_group` and `update_group` take `skills`, and `get_group` returns them.
## Limits
| | Limit |
| - | - |
| Skill lists | 20 per organization |
| Skills | 5,000 per list |
| List name | 80 characters |
| Skill name | 200 characters |
| Code | 64 characters |
| Description | 1,000 characters |
| Web page | 500 characters. It must start with `https://`. |
| CSV import | 1 MB and 1,000 skills per file |
Skills from ESCO, European Commission.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.