Skip to content

Commit dfffe26

Browse files
jean-de-botjean-de-bot
committed
feat: add AgentSkill for bi-directional anchor translation
Adds a skill following the AgentSkills.io specification that enables agents to: 1. Recognize verbose descriptions and identify the semantic anchor term 2. Suggest relevant anchors when users ask for methodology/guidance Includes: - SKILL.md with frontmatter and instructions - references/catalog.md with 50+ anchors organized by category Compatible with Claude Code, Codex, Cursor, and other skills-compatible agent products.
1 parent 5fa2656 commit dfffe26

2 files changed

Lines changed: 278 additions & 0 deletions

File tree

‎skill/semantic-anchor-translator/SKILL.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: semantic-anchor-translator
3+
description: Bi-directional translator between verbose descriptions and established terminology (semantic anchors). Use when (1) user describes a concept verbosely and you want to identify the precise term, or (2) user asks for methodology/approach and you want to suggest relevant anchors. Covers 50+ terms across testing, architecture, design principles, problem-solving, requirements, documentation, and strategic planning.
4+
metadata:
5+
author: LLM-Coding
6+
version: "1.0"
7+
source: https://github.com/LLM-Coding/Semantic-Anchors
8+
license: MIT
9+
---
10+
11+
# Semantic Anchor Translator
12+
13+
Translate between natural language and established terminology that activates rich knowledge domains.
14+
15+
## What are Semantic Anchors?
16+
17+
Semantic anchors are well-defined terms, methodologies, and frameworks that serve as reference points when communicating. They act as shared vocabulary that triggers specific, contextually rich knowledge.
18+
19+
**Example:** Instead of "write tests first, mock dependencies, work from outside-in" → say **"TDD, London School"**
20+
21+
## Two Modes
22+
23+
### Recognition Mode (verbose → anchor)
24+
25+
When user describes something like:
26+
- "I want to categorize things so they don't overlap and cover everything"
27+
- "I need to structure docs into tutorials, how-tos, explanations, and reference"
28+
- "Start with the conclusion, then give supporting details"
29+
30+
Respond with the anchor term + brief validation:
31+
> You're describing **MECE Principle** (Mutually Exclusive, Collectively Exhaustive).
32+
33+
### Guidance Mode (question → anchors)
34+
35+
When user asks for direction:
36+
- "How should I document architecture decisions?"
37+
- "What's a good way to prioritize requirements?"
38+
- "How do I debug this systematically?"
39+
40+
Suggest relevant anchors:
41+
> For architecture decisions: **ADR according to Nygard** or **MADR**. Both provide lightweight templates for capturing context, decision, and consequences.
42+
43+
## Response Pattern
44+
45+
1. Identify the anchor (or 2-3 if ambiguous)
46+
2. One-sentence explanation of why it matches
47+
3. Optional: related anchors they might also find useful
48+
4. If unsure: ask clarifying question
49+
50+
Keep responses concise — the value is precision, not explanation.
51+
52+
## Catalog Reference
53+
54+
Full catalog with categories, roles, and core concepts: [references/catalog.md](references/catalog.md)
55+
56+
Browse online: https://llm-coding.github.io/Semantic-Anchors/
57+
58+
## Quick Category Index
59+
60+
| Category | Key Anchors |
61+
|----------|-------------|
62+
| Testing | TDD Chicago/London, Testing Pyramid, Mutation Testing, Property-Based Testing |
63+
| Architecture | Clean Architecture, Hexagonal, DDD, arc42, C4, ADR, MADR |
64+
| Design | SOLID, DRY, SPOT, SSOT, Fowler Patterns |
65+
| Problem-Solving | Five Whys, Feynman Technique, Rubber Duck, Devil's Advocate |
66+
| Requirements | MoSCoW, EARS, User Story Mapping, JTBD, Impact Mapping |
67+
| Communication | BLUF, Pyramid Principle, MECE, Chatham House Rule |
68+
| Strategic | Cynefin, Wardley Mapping, Pugh Matrix |
69+
| Documentation | Diátaxis, Docs-as-Code |

‎skill/semantic-anchor-translator/references/catalog.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Semantic Anchors Catalog
2+
3+
Source: https://github.com/LLM-Coding/Semantic-Anchors
4+
5+
## Testing & Quality
6+
7+
### TDD, London School
8+
- **Also known as:** Mockist TDD, Outside-In TDD
9+
- **Proponents:** Steve Freeman, Nat Pryce
10+
- **Core:** Mock-heavy, outside-in development, interaction-based testing, interface discovery
11+
12+
### TDD, Chicago School
13+
- **Also known as:** Classicist TDD, Detroit School
14+
- **Proponents:** Kent Beck, Martin Fowler
15+
- **Core:** State-based testing, real objects over mocks, refactoring-focused
16+
17+
### Testing Pyramid
18+
- **Core:** Many unit tests, fewer integration tests, fewest E2E tests
19+
20+
### Mutation Testing
21+
- **Proponents:** Richard Lipton, Richard DeMillo
22+
- **Core:** Inject faults into code, verify tests catch them
23+
24+
### Property-Based Testing
25+
- **Core:** Test properties/invariants with generated inputs (QuickCheck, Hypothesis)
26+
27+
### IEC 61508 SIL Levels
28+
- **Proponents:** International Electrotechnical Commission
29+
- **Core:** Safety integrity levels for safety-critical systems
30+
31+
## Software Architecture
32+
33+
### Clean Architecture
34+
- **Core:** Dependency rule, entities at center, frameworks at edge
35+
36+
### Hexagonal Architecture (Ports & Adapters)
37+
- **Core:** Business logic isolated via ports, adapters for external systems
38+
39+
### Domain-Driven Design (DDD)
40+
- **Proponents:** Eric Evans
41+
- **Core:** Ubiquitous language, bounded contexts, aggregates, entities, value objects
42+
43+
### arc42 Architecture Documentation
44+
- **Proponents:** Gernot Starke, Peter Hruschka
45+
- **Core:** 12-section template for documenting software architecture
46+
47+
### C4-Diagrams
48+
- **Core:** Context, Container, Component, Code — 4 zoom levels
49+
50+
### ADR according to Nygard
51+
- **Proponents:** Michael Nygard
52+
- **Core:** Lightweight decision records: Title, Status, Context, Decision, Consequences
53+
54+
### MADR
55+
- **Proponents:** Oliver Kopp, Olaf Zimmermann
56+
- **Core:** Markdown ADR template with options considered section
57+
58+
### GoM (Guidelines of Modeling)
59+
- **Proponents:** Jörg Becker, Michael Rosemann
60+
- **Core:** Principles for creating understandable, consistent models
61+
62+
## Design Principles
63+
64+
### SOLID Principles
65+
- **Core:** Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
66+
67+
### DRY (Don't Repeat Yourself)
68+
- **Core:** Every piece of knowledge has single, unambiguous representation
69+
70+
### SPOT (Single Point of Truth)
71+
- **Core:** One authoritative source for each piece of data/logic
72+
73+
### SSOT (Single Source of Truth)
74+
- **Core:** One system is the master for specific data
75+
76+
### Patterns of Enterprise Application Architecture (PEAA)
77+
- **Proponents:** Martin Fowler
78+
- **Core:** Repository, Unit of Work, Data Mapper, Active Record, etc.
79+
80+
## Problem-Solving
81+
82+
### Five Whys (Ohno)
83+
- **Proponents:** Taiichi Ohno (Toyota)
84+
- **Core:** Ask "why" repeatedly to find root cause
85+
86+
### Feynman Technique
87+
- **Proponents:** Richard Feynman
88+
- **Core:** Explain concept simply, identify gaps, refine understanding
89+
90+
### Rubber Duck Debugging
91+
- **Core:** Explain code line-by-line to find bugs
92+
93+
### Devil's Advocate
94+
- **Core:** Argue against proposal to stress-test it
95+
96+
### Morphological Box
97+
- **Proponents:** Fritz Zwicky
98+
- **Core:** Matrix of parameters × options to explore solution space
99+
100+
### Chain of Thought (CoT)
101+
- **Proponents:** Wei et al. (Google Research, 2022)
102+
- **Core:** Step-by-step reasoning in prompts for better LLM outputs
103+
104+
### Cynefin Framework
105+
- **Proponents:** Dave Snowden
106+
- **Core:** Clear, Complicated, Complex, Chaotic, Confused — match approach to domain
107+
108+
## Requirements Engineering
109+
110+
### MoSCoW
111+
- **Proponents:** Dai Clegg
112+
- **Core:** Must have, Should have, Could have, Won't have
113+
114+
### EARS-Requirements
115+
- **Core:** Easy Approach to Requirements Syntax — templates for unambiguous requirements
116+
117+
### User Story Mapping
118+
- **Core:** 2D map: user activities (horizontal) × priority (vertical)
119+
120+
### Jobs To Be Done (JTBD)
121+
- **Proponents:** Clayton Christensen, Alan Klement, Bob Moesta
122+
- **Core:** Focus on the "job" users hire your product to do
123+
124+
### Impact Mapping
125+
- **Core:** Why → Who → How → What tree for goal-oriented planning
126+
127+
### Problem Space NVC
128+
- **Core:** Needs-Value-Constraints framework for problem definition
129+
130+
## Communication & Presentation
131+
132+
### BLUF (Bottom Line Up Front)
133+
- **Proponents:** US Military
134+
- **Core:** Lead with conclusion/recommendation, then details
135+
136+
### Pyramid Principle
137+
- **Proponents:** Barbara Minto
138+
- **Core:** Start with answer, group supporting arguments, logical order
139+
140+
### MECE Principle
141+
- **Core:** Mutually Exclusive, Collectively Exhaustive — no overlaps, no gaps
142+
143+
### Chatham House Rule
144+
- **Proponents:** Chatham House
145+
- **Core:** Info can be used but not attributed to speaker/org
146+
147+
### Socratic Method
148+
- **Core:** Ask questions to stimulate critical thinking and illuminate ideas
149+
150+
## Documentation
151+
152+
### Diátaxis Framework
153+
- **Core:** 4 quadrants: Tutorials, How-to guides, Explanations, Reference
154+
155+
### Docs-as-Code
156+
- **Proponents:** Ralf D. Müller
157+
- **Core:** Docs in version control, CI/CD, same workflow as code
158+
159+
## Development Workflow
160+
161+
### Conventional Commits
162+
- **Proponents:** Benjamin E. Coe, James J. Womack, Steve Mao
163+
- **Core:** Structured commit messages: type(scope): description
164+
165+
### Semantic Versioning (SemVer)
166+
- **Core:** MAJOR.MINOR.PATCH — breaking, feature, fix
167+
168+
### BEM Methodology
169+
- **Proponents:** Yandex
170+
- **Core:** Block__Element--Modifier CSS naming convention
171+
172+
### Mental Model (Naur)
173+
- **Proponents:** Peter Naur
174+
- **Core:** Programming as theory building — knowledge lives in developers' heads
175+
176+
### TIMTOWTDI
177+
- **Core:** There Is More Than One Way To Do It — Perl philosophy
178+
179+
### SOTA (State-of-the-Art)
180+
- **Core:** Current best-known methods/results in a field
181+
182+
### Regulated Environment
183+
- **Proponents:** FDA, EMA, ISO 9001, IEC 62304, GAMP 5
184+
- **Core:** Compliance requirements for medical, pharma, safety-critical
185+
186+
### todo.txt-flavoured Markdown
187+
- **Core:** GitHub task lists + todo.txt priorities/contexts/projects
188+
189+
## Statistical Methods
190+
191+
### SPC (Statistical Process Control)
192+
- **Proponents:** Walter A. Shewhart, W. Edwards Deming
193+
- **Core:** Monitor process stability with statistical methods
194+
195+
### Control Chart (Shewhart)
196+
- **Core:** Plot data over time with control limits
197+
198+
### Nelson Rules
199+
- **Core:** 8 rules for detecting non-random patterns in control charts
200+
201+
## Strategic Planning
202+
203+
### Wardley Mapping
204+
- **Proponents:** Simon Wardley
205+
- **Core:** Value chain × evolution stage for strategic positioning
206+
207+
### Pugh Matrix
208+
- **Proponents:** Stuart Pugh
209+
- **Core:** Decision matrix comparing options against criteria with baseline

0 commit comments

Comments
 (0)