diff --git a/docs/agentskill.adoc b/docs/agentskill.adoc new file mode 100644 index 0000000..95ced31 --- /dev/null +++ b/docs/agentskill.adoc @@ -0,0 +1,135 @@ += AgentSkill: Semantic Anchor Translator + +The Semantic Anchors project includes an **AgentSkill** that teaches AI coding assistants to recognize and suggest semantic anchors during your work. + +== What does it do? + +The skill operates in two modes: + +=== Recognition Mode (verbose -> anchor) + +When you describe a concept in your own words, the AI identifies the matching semantic anchor: + +[quote] +____ +*You:* "I want to categorize things so they don't overlap and cover everything" + +*AI:* You're describing **MECE Principle** (Mutually Exclusive, Collectively Exhaustive). +____ + +=== Guidance Mode (question -> anchors) + +When you ask for methodology advice, the AI suggests relevant anchors: + +[quote] +____ +*You:* "How should I document architecture decisions?" + +*AI:* For architecture decisions: **ADR according to Nygard** or **MADR**. Both provide lightweight templates for capturing context, decision, and consequences. +____ + +== Installation + +The skill follows the https://agentskills.io[agentskills.io] specification and can be used with any compatible AI coding assistant. + +=== Claude Code + +Add to your project's `CLAUDE.md`: + +[source] +---- +## Skills + +Use the semantic-anchor-translator skill from: +https://github.com/LLM-Coding/Semantic-Anchors/tree/main/skill/semantic-anchor-translator +---- + +Or reference the skill's `SKILL.md` directly in your project configuration. + +=== GitHub Copilot + +Add to `.github/copilot-instructions.md` in your repository: + +[source] +---- +## Semantic Anchors + +When the user describes a concept verbosely, identify the precise +semantic anchor term. When asked for methodology advice, suggest +relevant anchors from the catalog. + +Reference: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md +---- + +=== Cursor + +Add to `.cursor/rules` or `.cursorrules` in your project: + +[source] +---- +## Semantic Anchors + +Use the semantic-anchor-translator skill to recognize and suggest +established terminology. Catalog: +https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md +---- + +=== Amazon Kiro + +Add to your project's `specs/` directory or include in a spec file: + +[source] +---- +## Semantic Anchors + +When the user describes a concept verbosely, identify the precise +semantic anchor term. When asked for methodology advice, suggest +relevant anchors from the catalog. + +Reference: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md +---- + +=== Other AI Tools + +Any AI coding assistant that supports custom instructions or system prompts can use the skill. Point it to the catalog at: + +https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/SKILL.md + +== Catalog Overview + +The skill covers **90+ semantic anchors** across these categories: + +[cols="1,3"] +|=== +| Category | Key Anchors + +| Testing & Quality +| TDD Chicago/London, BDD, Testing Pyramid, Mutation Testing, Property-Based Testing, Test Double + +| Software Architecture +| Clean Architecture, Hexagonal, DDD, arc42, C4, ADR, MADR, CQRS, EDA + +| Design Principles +| SOLID (5 sub-principles), GoF Design Patterns (23 sub-patterns), DRY, SPOT, YAGNI + +| Problem-Solving +| Five Whys, Feynman Technique, Rubber Duck Debugging, Devil's Advocate, Cynefin + +| Requirements Engineering +| MoSCoW, EARS, User Story Mapping, JTBD, Impact Mapping + +| Communication +| BLUF, Pyramid Principle, MECE, Chatham House Rule, Socratic Method + +| Documentation +| Diataxis Framework, Docs-as-Code + +| Strategic Planning +| Wardley Mapping, Pugh Matrix +|=== + +The full catalog with descriptions, proponents, and core concepts is available at https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md[catalog.md on GitHub]. + +== Contributing + +When you add a new anchor to the catalog, please also update the AgentSkill catalog at `skill/semantic-anchor-translator/references/catalog.md` so AI agents can discover it. + +See link:#/contributing[Contributing] for the full contribution workflow. diff --git a/docs/agentskill.de.adoc b/docs/agentskill.de.adoc new file mode 100644 index 0000000..6d07e6a --- /dev/null +++ b/docs/agentskill.de.adoc @@ -0,0 +1,135 @@ += AgentSkill: Semantic Anchor Translator + +Das Semantic Anchors Projekt enthält einen **AgentSkill**, der KI-Coding-Assistenten beibringt, semantische Anker während der Arbeit zu erkennen und vorzuschlagen. + +== Was macht er? + +Der Skill arbeitet in zwei Modi: + +=== Erkennungsmodus (ausführlich -> Anker) + +Wenn du ein Konzept in eigenen Worten beschreibst, identifiziert die KI den passenden semantischen Anker: + +[quote] +____ +*Du:* "Ich möchte Dinge so kategorisieren, dass sie sich nicht überlappen und alles abdecken" + +*KI:* Du beschreibst das **MECE Principle** (Mutually Exclusive, Collectively Exhaustive). +____ + +=== Beratungsmodus (Frage -> Anker) + +Wenn du nach Methodik-Empfehlungen fragst, schlägt die KI relevante Anker vor: + +[quote] +____ +*Du:* "Wie sollte ich Architekturentscheidungen dokumentieren?" + +*KI:* Für Architekturentscheidungen: **ADR nach Nygard** oder **MADR**. Beide bieten leichtgewichtige Templates für Kontext, Entscheidung und Konsequenzen. +____ + +== Installation + +Der Skill folgt der https://agentskills.io[agentskills.io]-Spezifikation und kann mit jedem kompatiblen KI-Coding-Assistenten verwendet werden. + +=== Claude Code + +Füge in die `CLAUDE.md` deines Projekts hinzu: + +[source] +---- +## Skills + +Use the semantic-anchor-translator skill from: +https://github.com/LLM-Coding/Semantic-Anchors/tree/main/skill/semantic-anchor-translator +---- + +Oder referenziere die `SKILL.md` des Skills direkt in deiner Projektkonfiguration. + +=== GitHub Copilot + +Füge in `.github/copilot-instructions.md` in deinem Repository hinzu: + +[source] +---- +## Semantic Anchors + +When the user describes a concept verbosely, identify the precise +semantic anchor term. When asked for methodology advice, suggest +relevant anchors from the catalog. + +Reference: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md +---- + +=== Cursor + +Füge in `.cursor/rules` oder `.cursorrules` in deinem Projekt hinzu: + +[source] +---- +## Semantic Anchors + +Use the semantic-anchor-translator skill to recognize and suggest +established terminology. Catalog: +https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md +---- + +=== Amazon Kiro + +Füge in das `specs/`-Verzeichnis deines Projekts oder in eine Spec-Datei hinzu: + +[source] +---- +## Semantic Anchors + +When the user describes a concept verbosely, identify the precise +semantic anchor term. When asked for methodology advice, suggest +relevant anchors from the catalog. + +Reference: https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md +---- + +=== Andere KI-Tools + +Jeder KI-Coding-Assistent, der benutzerdefinierte Anweisungen oder System-Prompts unterstützt, kann den Skill nutzen. Verweise auf den Katalog unter: + +https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/SKILL.md + +== Katalogübersicht + +Der Skill umfasst **90+ semantische Anker** in folgenden Kategorien: + +[cols="1,3"] +|=== +| Kategorie | Wichtige Anker + +| Testing & Qualität +| TDD Chicago/London, BDD, Testing Pyramid, Mutation Testing, Property-Based Testing, Test Double + +| Software-Architektur +| Clean Architecture, Hexagonal, DDD, arc42, C4, ADR, MADR, CQRS, EDA + +| Design-Prinzipien +| SOLID (5 Unterprinzipien), GoF Design Patterns (23 Untermuster), DRY, SPOT, YAGNI + +| Problemlösung +| Five Whys, Feynman Technique, Rubber Duck Debugging, Devil's Advocate, Cynefin + +| Requirements Engineering +| MoSCoW, EARS, User Story Mapping, JTBD, Impact Mapping + +| Kommunikation +| BLUF, Pyramid Principle, MECE, Chatham House Rule, Socratic Method + +| Dokumentation +| Diataxis Framework, Docs-as-Code + +| Strategische Planung +| Wardley Mapping, Pugh Matrix +|=== + +Der vollständige Katalog mit Beschreibungen, Vertretern und Kernkonzepten ist unter https://github.com/LLM-Coding/Semantic-Anchors/blob/main/skill/semantic-anchor-translator/references/catalog.md[catalog.md auf GitHub] verfügbar. + +== Mitwirken + +Wenn du einen neuen Anker zum Katalog hinzufügst, aktualisiere bitte auch den AgentSkill-Katalog unter `skill/semantic-anchor-translator/references/catalog.md`, damit KI-Agenten ihn finden können. + +Siehe link:#/contributing[Mitwirken] für den vollständigen Beitrags-Workflow. diff --git a/scripts/render-docs.js b/scripts/render-docs.js index 0c217b3..6daa1c3 100644 --- a/scripts/render-docs.js +++ b/scripts/render-docs.js @@ -64,5 +64,8 @@ renderFile(path.join(ROOT, 'CONTRIBUTING.de.adoc'), path.join(WEB_PUBLIC, 'CONTR renderFile(path.join(ROOT, 'docs/changelog.adoc'), path.join(WEB_DOCS, 'changelog.html')) +renderFile(path.join(ROOT, 'docs/agentskill.adoc'), path.join(WEB_DOCS, 'agentskill.html')) +renderFile(path.join(ROOT, 'docs/agentskill.de.adoc'), path.join(WEB_DOCS, 'agentskill.de.html')) + // all-anchors.adoc uses include:: directives — resolved automatically in Node.js renderFile(path.join(ROOT, 'docs/all-anchors.adoc'), path.join(WEB_DOCS, 'all-anchors.html')) diff --git a/website/src/components/header.js b/website/src/components/header.js index 9cd8aa2..23ea2f1 100644 --- a/website/src/components/header.js +++ b/website/src/components/header.js @@ -38,6 +38,7 @@ export function renderHeader() { ${i18n.t('nav.about')} ${i18n.t('nav.contributing')} ${i18n.t('nav.changelog')} + ${i18n.t('nav.agentskill')}
diff --git a/website/src/main.js b/website/src/main.js index 6fb5541..4fa70ad 100644 --- a/website/src/main.js +++ b/website/src/main.js @@ -103,6 +103,7 @@ function initApp() { addRoute('/about', renderAboutPage) addRoute('/contributing', renderContributingPage) addRoute('/changelog', renderChangelogPage) + addRoute('/agentskill', renderAgentSkillPage) addRoute('/all-anchors', renderAllAnchorsPage) const app = document.querySelector('#app') @@ -188,6 +189,15 @@ function renderChangelogPage() { loadDocContent('docs/changelog.adoc') } +function renderAgentSkillPage() { + const pageContent = document.getElementById('page-content') + if (!pageContent) return + + pageContent.innerHTML = renderDocPage() + updateActiveNavLink() + loadDocContent('docs/agentskill.adoc') +} + function renderAllAnchorsPage() { const pageContent = document.getElementById('page-content') if (!pageContent) return @@ -393,6 +403,8 @@ function handleLanguageChange() { loadDocContent('CONTRIBUTING.adoc') } else if (currentRoute === '/changelog') { loadDocContent('docs/changelog.adoc') + } else if (currentRoute === '/agentskill') { + loadDocContent('docs/agentskill.adoc') } else if (currentRoute === '/all-anchors') { loadDocContent('docs/all-anchors.adoc') } else if (currentRoute === '/') { diff --git a/website/src/translations/de.json b/website/src/translations/de.json index ade9f8b..1f010af 100644 --- a/website/src/translations/de.json +++ b/website/src/translations/de.json @@ -9,6 +9,7 @@ "nav.about": "Über", "nav.contributing": "Mitwirken", "nav.changelog": "Änderungsprotokoll", + "nav.agentskill": "AgentSkill", "main.heading": "Semantic Anchors erkunden", "main.subheading": "Ein kuratierter Katalog klar definierter Begriffe, Methoden und Frameworks für effektive LLM-Kommunikation.", "main.aboutLink": "Über", diff --git a/website/src/translations/en.json b/website/src/translations/en.json index b82921c..8b43df2 100644 --- a/website/src/translations/en.json +++ b/website/src/translations/en.json @@ -9,6 +9,7 @@ "nav.about": "About", "nav.contributing": "Contributing", "nav.changelog": "Changelog", + "nav.agentskill": "AgentSkill", "main.heading": "Explore Semantic Anchors", "main.subheading": "A curated catalog of well-defined terms, methodologies, and frameworks for effective LLM communication.", "main.aboutLink": "About",