AI Skills¶

Configure custom AI skills that enhance AI interactions. This tab lets you manage a library of markdown-based skills that are automatically or manually included in AI requests. Open via AI → AI Manager → AI Skills; stored in ~/.kortty/global-settings.xml.

Global Settings¶

A count line below the list summarizes the whole library — Total, Active (enabled and not hidden), and Inactive/hidden — regardless of the current search or hidden filter.

Skill Editor Fields¶

When you select or create a skill, the right panel shows per-skill fields. Each skill is persisted individually in the skill list.

The skill library is stored in global-settings.xml, which cannot hold certain invisible characters: control characters other than tab, line feed and carriage return, U+FFFE, U+FFFF and half of a surrogate pair. Such a character can arrive when you paste into the Skill Markdown editor. A field that contains one shows a message below it that names the character, for example U+0007, and Save refuses to save the library and selects the skill until you remove the character. When you close the AI Manager with such a skill, korTTY saves your other changes and keeps the last saved version of that skill, or leaves out a skill that was never saved. Import removes such characters from the name, description, tags and Markdown of the imported file.

Built-in skills¶

korTTY ships 39 built-in best-practice skills covering shells (Bash, KornShell, Zsh, Csh, POSIX sh, PowerShell), programming languages (Python, C, C++, Java, C#, JavaScript, Visual Basic, SQL, R, Rust, Go, PHP, Swift, Assembly, Macro Assembler, Ruby, Perl, Lua, Groovy, TypeScript, Kotlin, Dart), markup and data formats (HTML, XML, YAML, JSON) and automation/observability tools (Puppet, Ansible, Azure DevOps Pipelines, Jenkins Declarative and Scripted Pipelines, Filebeat, Logstash). Each skill carries professional guidance on code commenting, robustness, common pitfalls to avoid, and language-specific security practices. They are added to the library on first start and appear with a Built-in badge.

Built-in skills behave like your own skills — they can be edited, deactivated and assigned to connections — with these differences:

• They cannot be deleted, only hidden. Hide removes a built-in from the list and from all skill pickers, and a hidden built-in is no longer sent with any AI request — even on connections it was previously assigned to. Show hidden built-in skills reveals hidden entries, marked with a Hidden badge, so they can be brought back with Unhide.
• Unmodified built-ins update automatically. When a new korTTY release ships improved skill content, unchanged built-ins are replaced silently at startup (your Active/hidden choices are kept).
• Modified built-ins are never touched. Once you edit a built-in it shows a Built-in (modified) badge and stops auto-updating. Reset to shipped version discards your changes and restores the delivered version your edits were based on. If a newer delivered version exists, the entry shows 🔄 Update available and Update to latest shipped version adopts it.
• Your own skills always take precedence. When one of your enabled skills carries a tag matching a built-in's topic (for example a personal skill tagged perl), the built-in is suppressed: it shows Overridden by user skill, is grayed out, and is no longer sent with any AI request. Deleting or deactivating your skill immediately reactivates the built-in.
• Deactivated, hidden and overridden entries are rendered grayed out; this works in every application design theme.

External skills¶

The External view lists skills imported from internet skill directories. External skills live in the same library as your own skills: once you enable one, it is selected and sent exactly like a local skill. The count on each switch button shows how many skills each view holds.

When an external skill is selected, the banner above the editor shows its provider, its source and the imported revision. Open source opens the skill's page in the browser. If you edit the text or the description, the banner and the list mark the skill as Changed locally; Shorten... never changes the text of an imported skill, only its learned rules. After Check for updates has found a newer version, Show update… opens a side-by-side comparison of your version and the provider's version. Apply update replaces the text and description and keeps your name, tags, target, active state and learned rules; a skill imported before descriptions were tracked keeps its description. A skill that is Changed locally is never overwritten, and the dialog says so: it offers Import as copy, which adds the provider version as a new, deactivated skill named after the revision, and Skip this version, which hides that revision while a newer one is still offered. Nothing is updated without a click, and every change takes effect when you click Save.

Importing skills¶

Choose a provider, enter a search and click Search. Selecting a result loads its SKILL.md into the preview. The results table shows each skill's name, source, GitHub stars and description; a ✓ before the name marks a skill that is already in the library. Select one or more results and click Import selected; results marked ✓ are skipped. What you enter depends on the provider type:

Directories such as agenticskills.io and skills.sh publish their skills as GitHub repositories, so the GitHub provider imports from all of them. korTTY reads repositories through the GitHub REST API at https://api.github.com (API version 2022-11-28) and remembers the Git revision of each imported SKILL.md, so a commit that changes other files of the repository is not reported as an update. Without a token GitHub allows 60 requests an hour; an import takes one or two. GitHub only answers a keyword search with a token: without one, the dialog explains this and offers Search SkillsMP instead, which searches the same GitHub skills without signing in. Keywords do not have to match exactly; every word has to appear somewhere in the SKILL.md.

The SkillsMP provider searches the SkillsMP index through https://skillsmp.com/api/v1/skills/search. Without an API key SkillsMP allows 50 searches a day, with a key 500. The skills it finds are downloaded from GitHub through the active GitHub provider for github.com, with that provider's token.

Providers¶

Providers… opens a table of skill providers that you can extend as you like. korTTY starts with a GitHub and a SkillsMP provider; add more with + Add, for example a GitHub Enterprise server or a team's own server. Deleting a provider keeps the skills imported from it, but they can no longer be checked for updates.

Test connection checks that the provider answers and accepts the credentials, and shows the remaining request quota where the provider reports one. A token or password is encrypted with the master password when you click Save; if the vault is locked, korTTY offers to unlock it. Leave the field empty to keep a stored token, or tick Remove stored token/password to delete it.

Skills created by korTTY and learned rules¶

korTTY can save rules that you confirm into your skills, and it can create a skill for a topic that has none yet. Nothing is saved without your confirmation: the rule card shows the exact text and where it goes, and Save writes it. The switch korTTY may create skills and save learned rules in them controls both, and the enterprise policy can lock it.

A rule that names a connection goes into that connection's memory; a rule about a topic that already has a skill, built-in or your own, goes into that skill's learned rules; a rule about a language or tool without a skill creates one; any other rule goes into the global memory. The memory itself is described in AI memory.

• A skill korTTY created shows the badge NEW · created by korTTY until you select it in the list; then it shows korTTY. The skill the list selects by itself when it opens does not count.
• A +N rule(s) chip counts the learned rules you have not seen yet; opening the skill marks them as seen and removes the chip.
• The editor lists the learned rules of a skill under Learned rules, shown only when the skill has any. Edit changes a rule's text in a dialog, Delete removes it after a confirmation, and both are saved with the skill when you click Save.
• Learned rules are sent with their skill whenever the skill is selected for a request, as long as the memory is on and the policy allows it.

Rules are proposed from your messages only in the Suggest rules learning mode; Remember as rule… saves a rule that you write yourself.

Secrets in skills¶

korTTY does not store a possible password, key or token in a skill, a learned rule, the memory or an approved memory file. The check looks for keyword phrases in German and English, key=value assignments (also in .env files and command-line flags), long random-looking strings, token formats it knows, and values saved in the password vault while the vault is unlocked.

When you change a skill so that it holds a possible secret, Save refuses to save the library and selects that skill. A flagged skill that you do not change does not block Save; its badge stays until the secret is removed. The message names the line, the field and the kind of secret, never the value, for example Line 4 in the skill text looks like it holds a secret (a password or token assignment). Remove it and try again. A Markdown file or a skill from the internet that holds a finding is refused on import in the same way.

At startup korTTY checks the existing skills and marks one that holds a possible secret with a ⚠ possible secret badge in the list. It does not change or delete that skill. A flagged skill is still sent with requests until the secret line is removed; only the outbound masking applies.

The check is no guarantee. A password you chose yourself, without a keyword and not saved in the vault, cannot be recognized reliably, so do not write one into a skill.

Skill statistics¶

Statistics in the list's header opens the statistics of your skills: how often each one was sent with a request, how large it is and how that changes. The figures come from the local file stats/skill-usage.json, see Configuration files.

The four figures at the top are Automatic uses, Average size of active skills in tokens, Skill tokens sent and Growth per month in tokens per month. The stacked bar chart shows the uses per skill over the range: the eight most used skills and Others. The table lists each skill, most used first, with its badge under the name, automatic and pinned uses, average and current size, growth per month and in percent, last use and learned rules. Select a row to see its size history below the table.

Hints name the skills to review: one not used for 90 days, one that more than doubled within 30 days, and one above 1,000 tokens. The last two offer Shorten....

Shorten... asks the default AI profile for a shorter version of the skill and of its learned rules, shows the change as a diff with the token sizes before and after, and saves nothing until you click Apply. The text of a skill you wrote yourself can be shortened. For a built-in or an imported skill only its learned rules are shortened, so its text keeps receiving updates. Set a default AI profile first; the dialog says so when none is set.

Daily values are kept for 400 days, monthly values for five years and yearly values without a limit. The enterprise policy key statistics in [rule.ai-memory] can switch recording off for everyone; see Enterprise policy.

Notes¶