Microsoft AzureKnown publisherAzure/azure-sdk-tools/.github/skills/azure-typespec-sdk-naming/SKILL.mdazure-typespec-sdk-naming
Skill134 starsChanged 3 months agoMITView on GitHub
Apply shared SDK naming guidance during TypeSpec authoring, customization, and read-only review. WHEN: "plan SDK names", "check TypeSpec SDK naming", "review SDK naming conventions", "fix naming in client.tsp", "add a language-scoped clientName override". Initially covers C# management SDKs.
In this repository44 other files it gives its agents.
- packages/python-packages/apiview-copilot/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- azsdk-common-apiview-feedback-resolutionSkill
- azsdk-common-generate-sdk-locallySkill
- azsdk-common-generate-sdk-pipelineSkill
- azsdk-common-pipeline-analysisSkill
- azsdk-common-pipeline-fixerSkill
- azsdk-common-prepare-release-planSkill
- azsdk-common-sdk-breaking-changeSkill
- azsdk-common-sdk-releaseSkill
- azure-typespec-assessmentSkill
- azure-typespec-authorSkill
- code-reviewSkill
- eval-authoring-skillSkill
- eval-authoring-toolSkill
- eval-authoring-workflowSkill
- markdown-token-optimizerSkill
- sdk-ai-bot-eval-datasetSkill
- sdk-ai-bot-run-evaluationSkill
- skill-authoringSkill
- add-endpointSkill
- audit-filtersSkill
- dev-setupSkill
- kb-searchSkill
- report-active-reviewsSkill
- report-apiview-metricsSkill
- report-architect-commentsSkill
- report-feedbackSkill
- report-memorySkill
- report-revisionsSkill
- run-evalsSkill
- run-metricsSkill
- update-guidelinesSkill
- apiview-feedback-resolutionSkill
- azure-typespec-authorSkill
- generate-sdk-locallySkill
- azsdk-common-live-and-recorded-testsSkill
- markdown-token-optimizerSkill
- pipeline-troubleshootingSkill
- azsdk-common-prepare-release-planSkill
- azsdk-common-sdk-releaseSkill
- skill-authoringSkill
- pr-review-helpSkill
- pr-reviewSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Apply only when authorized: Follow the apply workflow: directly edit scoped naming overrides in client.tsp and necessary imports/loading.
- Distinctive: line 29
If invoked by another skill, return naming decisions to that workflow.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
TypeSpec SDK Naming
One source of naming rules for authoring and read-only naming review. Read the naming dispatcher and only its applicable profiles.
Workflow
- Choose intent. Guidance/planning and review are read-only. Use apply only when the user or calling authoring workflow authorizes edits. Never interpret review feedback alone as permission to fix.
- Select coverage. Identify language and ARM/data-plane context from supplied evidence. Read the dispatcher's matching profile references before recommending names; invoking this skill does not load those rules. This is required in default client configuration planning as well as explicit naming requests. Resolve missing information only for affected naming decisions; do not block unrelated REST work.
- Evaluate. Apply compatibility before naming style: supplied evidence of a shipped SDK name makes that name the required output unless an intentional breaking rename is explicitly authorized. Apply naming conventions only to unshipped names. Preserve wire contracts and other languages. Return targets, proposed names, scopes, rationale, exceptions and blockers. Ordinary declaration authoring remains with the caller.
- Apply only when authorized. Follow the apply workflow: directly edit scoped naming overrides in
client.tspand necessary imports/loading. Do not callazsdk_customized_code_updatefor naming-only changes. Never edit SDK custom code or generated code for a TypeSpec naming fix. - Report evidence. Distinguish recommendations, applied changes and verified generated names. Review reports findings without writes or generation; after apply, validate as described in the apply workflow.
Consumers
azure-typespec-author: consult in guidance mode before authoring; use apply for planned SDK-only overrides.- Copilot reviewers: use review mode on the supplied changed declarations and SDK evidence, never apply.
- Direct naming-only
client.tsprequests use this skill; do not recursively invoke the full authoring workflow. Other SDK customization or generation requests remain with their existing workflows.
If invoked by another skill, return naming decisions to that workflow; do not start a separate assessment or SDK-generation workflow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.