# Conventions for sharing and documenting prompts [Skip to content](#lm-inhoud)Network/[NL](/en/community-conventies-voor-prompts)EN[Hubhub.llmnet.nlCompare models on task, language, cost and licence.](https://hub.llmnet.nl/en/)[Communitycommunity.llmnet.nlPrompt techniques, patterns and system prompts.](https://community.llmnet.nl/en/)[APIapi.llmnet.nlLLMs in production: rate limits, routing, structured output.](https://api.llmnet.nl/en/)[Consultancyconsultancy.llmnet.nlRolling out AI in an organisation, pilot to production.](https://consultancy.llmnet.nl/en/)[Newsnieuws.llmnet.nlAI developments, explained for the Netherlands.](https://nieuws.llmnet.nl/en/)[Benchmarkbenchmark.llmnet.nlMeasure AI quality yourself, on your own tasks.](https://benchmark.llmnet.nl/en/)[Careersvacatures.llmnet.nlAI roles, salaries and career paths in the Netherlands.](https://vacatures.llmnet.nl/en/)[Learnleren.llmnet.nlAI concepts in plain language, beginner to builder.](https://leren.llmnet.nl/en/)[Guidegids.llmnet.nlRun AI privately on your own Mac, PC, NAS or home server.](https://gids.llmnet.nl/en/)[Directorydirectory.llmnet.nlMapping the AI ecosystem: tools, models, companies.](https://directory.llmnet.nl/en/)[Radarradar.llmnet.nlSignals from X, research and communities for indie developers.](https://radar.llmnet.nl/en/)[Appsapps.llmnet.nlReviews of AI apps and open-source repos, with tips for builders.](https://apps.llmnet.nl/en/)[llmnet.nl — main site](https://llmnet.nl/en/)[](https://x.com/intent/post?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Fcommunity-conventies-voor-prompts&text=Conventions%20for%20sharing%20and%20documenting%20prompts)[](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Fcommunity-conventies-voor-prompts)[](https://www.reddit.com/submit?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Fcommunity-conventies-voor-prompts&title=Conventions%20for%20sharing%20and%20documenting%20prompts)[](#)[](https://x.com/intent/post?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Fcommunity-conventies-voor-prompts&text=Conventions%20for%20sharing%20and%20documenting%20prompts)[](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Fcommunity-conventies-voor-prompts)[](https://www.reddit.com/submit?url=https%3A%2F%2Fcommunity.llmnet.nl%2Fen%2Fcommunity-conventies-voor-prompts&title=Conventions%20for%20sharing%20and%20documenting%20prompts)[](#) # Conventions for sharing and documenting prompts By Ivo Donker — compiled with AI support · Last updated: August 7, 2026 When software teams integrate language models into production applications, the need quickly arises to hand off natural-language instructions between developers, data engineers, and domain experts. In many organizations this process happens ad hoc: developers copy text blocks through chat channels, save variants in personal note-taking apps, or embed loose instructions directly in application code. This inevitably leads to untraceable regressions, uncertainty about the intended language model, and loss of essential edge-case context. In modern application architectures, prompts are full-fledged source code. Exchanging and recording instructions therefore demands exactly the same technical discipline as software code, API specifications, and README documentation. Treating instructions formally requires the team to make standardized agreements about the full lifecycle of these artifacts. Read how to [treat prompts as code](https://community.llmnet.nl/en/prompt-versiebeheer) to safeguard clarity and reproducibility of changes in the development process. When setting up a professional workflow, it's essential to strictly separate three concepts. First, there's the version control mechanism, which stores and tracks textual changes in a repository. Second, there's the prompt library, which serves as the organized collection where the instructions live. Check out the overview of the [prompt library where shared prompts live](https://community.llmnet.nl/en/prompt-bibliotheek) to see how structured collections are organized in production environments. This article covers the third pillar: the organizational and technical conventions around documenting and handing off prompts. Without clear agreements, even the best-structured repository gets cluttered with unusable artifacts. ## Team Agreements Upfront: Naming, Metadata, and Frontmatter Before a team starts sharing instructions, clear agreements need to be established about the identification and metadata of prompt files. The absence of conventions leads to file names such as prompt_v2_final.txt, which carry no information at all about the purpose, the expected model, or the required input variables. Naming conventions should be based on semantic identifiers that describe the function of the prompt, independent of the author or the specific application layer. Use a hierarchical folder or file structure based on kebab-case notation following the pattern domein/subdomein/actie.prompt.md. (Assumption: teams that apply a strict hierarchical naming convention reduce the time spent searching for specific instructions within the team by 50%). In addition to the file name, every shared prompt file must include a standardized header block. YAML frontmatter offers the most suitable structure for this, since this format can be read by both human developers and automated CI/CD pipelines and linter tools. The team decides in advance which fields are mandatory within the organization and which remain optional. The mandatory metadata fields in the frontmatter include, at minimum: - id: A unique, immutable semantic key within the organization. - title: A short descriptive title for the instruction. - version: The semantic version numbering following the major.minor.patch scheme. - owner: The team or specific developer role responsible for maintenance. - target_model: The specifically tested language model, including the exact model version string from the provider. - parameters: The validated runtime parameters, such as temperature, top_p, and max_tokens. - inputs: A written-out list of all expected variables that get substituted at runtime. - outputs: A definition of the expected response type (for example, an encoded JSON schema or structured text). Including these fields prevents configuration parameters from staying hidden in application code, or a colleague running the prompt with incorrect model settings. Check out the guidelines on [prompt modularity and reusable components](https://community.llmnet.nl/en/prompt-modulariteit-herbruikbare-componenten) to learn how to break down complex instructions into maintainable building blocks that each carry their own frontmatter. ## The Documentation Block: Self-Contained, Runnable Instructions An important criterion for a well-documented prompt is that a colleague can run the instruction directly and effectively in a test environment or playground, without needing verbal explanation, access to application code, or additional context. This is achieved by embedding the prompt in a self-contained documentation block. The documentation block must include the following fixed components: - Functional Purpose: A clear description of the task the language model needs to perform and the intended business process. - Input and Output Specifications: An explicit declaration of all runtime variables with their data types, combined with a concrete JSON schema or a TypeScript interface for the expected output. - Constraints and Boundary Conditions: Known edge cases, topics the prompt must explicitly ignore, and instructions to prevent hallucinations or unwanted formatting. - Model and Runtime Configuration: The exact parameters with which the prompt was validated. Besides temperature and top_p, this also includes any stop sequences and the system role setting. - Token Budget: An indication of the expected number of tokens for both the instruction and the response. Use the [prompt token counter to estimate the token budget](https://community.llmnet.nl/en/prompt-tokenteller) before a new prompt version is released to the development team. The template below shows a standardized, directly copyable artifact for a prompt documentation block, including YAML frontmatter: --- id: "customer-support/ticket-classifier" title: "Klantenservice Ticket Classificatie en Entiteit-extractie" version: "1.2.0" owner: "team-support-engineering" target_model: "claude-3-5-sonnet-20241022" parameters: temperature: 0.0 max_tokens: 500 top_p: 1.0 inputs: - name: "ticket_body" type: "string" description: "De volledige tekst van het ingediende klantticket." - name: "customer_tier" type: "string" description: "Het serviceniveau van de klant (bijv. 'free', 'pro', 'enterprise')." outputs: type: "json_object" schema: category: "string" urgency: "string (low|medium|high|critical)" sentiment: "string (positive|neutral|negative)" action_required: "boolean" changelog: - version: "1.2.0" date: "2026-08-01" author: "Ivo Donker" change: "Toevoeging van customer_tier variabele voor nauwkeurigere bepaling van urgentie." --- # Functioneel Doel Deze prompt analyseert inkomende klantenservicetickets, bepaalt de categorie en urgentie, en extraheert gestructureerde metadata voor automatische routering in het helpdesksysteem. # Invoervariabelen - `ticket_body`: Platte tekst van de klant. - `customer_tier`: 'free', 'pro' of 'enterprise'. # Verwachte Uitvoer De uitvoer MOET een valide JSON-object zijn zonder aanvullende tekst of Markdown-fences buiten de JSON-structuur. Voorbeeld van geldige uitvoer: { "category": "billing", "urgency": "high", "sentiment": "negative", "action_required": true } # Beperkingen en Randvoorwaarden - Geen aannames doen over ontbrekende factuurnummers. - Indien de tekst in een andere taal dan het Nederlands is gesteld, toch analyseren maar de categorie 'multilingual-routing' toekennen. - Geen persoonsgegevens overnemen in de output-velden. # Prompt Instructie [SYSTEM] Je bent een gespecialiseerde verwerker van klantenservicetickets. Je analyseert de onderstaande tekst en retourneert uitsluitend een JSON-object dat voldoet aan de opgegeven specificatie. [USER] Klantniveau: {{customer_tier}} Ticketinhoud: {{ticket_body}} ## Hygiene and Safety: What NOT to Include When Sharing When exchanging prompts within teams or publishing templates, there's a real risk of leaking confidential information. Because instructions are written in natural language, the line between application logic and data blurs faster than with traditional code. Strict hygiene is necessary to prevent business-critical information from being inadvertently spread. The following data must never appear in shared prompt files under any circumstances: - Credentials and API Keys: Hardcoded tokens, passwords, database connection strings, or internal API endpoints belong in a secret manager or environment variables, never in the prompt text. - Personal Data (PII): Real names, email addresses, customer numbers, or financial data inserted as 'realistic examples' in few-shot examples. Use only fictitious, synthetic data for examples. - Confidential Internal Context: Unpublished project names, internal organizational structure, intellectual property, or specific vulnerabilities in internal systems. - Security-Sensitive Instructions: Detailed descriptions of internal security and validation mechanisms that could give malicious actors a foothold for prompt injections. When instructions are shared within an internationally composed team, there should also be clear agreements about the language used in the instructions and examples. See the article on [multilingual prompts for specific conventions](https://community.llmnet.nl/en/meertalige-prompts) for documenting instructions in international software teams, to avoid noise and misinterpretation by language models. ## The Difference Between Internal Sharing and Public Publishing The requirements placed on a documentation block vary depending on the scope of distribution. There's a fundamental difference between sharing a prompt within a closed development team and publicly publishing an instruction as an open-source artifact or as part of external API documentation. For internal distribution within an organization, documentation can rely on shared domain knowledge and internal standards. Internal jargon, references to specific microservices, and the organization's own frameworks don't need to be explained from scratch for every individual prompt, as long as the overarching context is preserved in the repository. The focus here is on processing speed, direct integration into the software architecture, and maintainability. For public publication, every assumed context falls away. A publicly released prompt must meet additional quality and safety requirements: - Full Self-Containment: The prompt must in no way depend on non-public internal templates, libraries, or specific middleware wrappers. - Cleaning Up Assumptions: All company-specific frameworks, abbreviations, and internal terminology must be replaced with generally accepted standards. - Explicit Licensing: The file must include a clear license designation (for example MIT or Apache 2.0) in the frontmatter, so users know under what terms the instruction may be reused. - Universal Examples: The included test input and expected output must be understandable to external developers with no knowledge of the specific business logic. To make this exchange run smoothly within teams, appropriate tooling is needed. The overview of [prompt management tools](https://directory.llmnet.nl/en/prompt-management-tools) compares suitable platforms and repository integrations that help teams manage shared instructions. ## Maintenance, Lifecycle, and Changelogs Documenting and delivering a prompt is not a one-time action. Language models change their behavior with provider updates, and application requirements keep evolving. A shared prompt that isn't actively maintained quickly turns into technical debt. (Assumption: prompts that haven't been reassessed against the latest model version for more than six months show unintended quality degradation in 30% of cases). Structured maintenance of shared prompts rests on three specific pillars: ### 1. Periodic Cleanup of Few-Shot Examples Few-shot examples created for an older model generation can backfire on newer models. Newer models often need fewer, or more specifically structured, examples to reach the same quality level. Check, at every major update of the target model, whether the embedded examples are still necessary and representative. ### 2. Managing Model Names and Provider Aliases Linking a shared prompt to a generic model alias such as gpt-4o or claude-3-5-sonnet creates risks. Providers regularly update the underlying model version behind these aliases. The documentation should therefore always record the exact, pinned version string (for example claude-3-5-sonnet-20241022), combined with the date on which the instruction was validated against that specific version. ### 3. Version History and Changelog per Prompt Every prompt file must have a changelog in the frontmatter or in the accompanying documentation. A changelog entry includes, at minimum, the version number, the date, the author, the reason for the change, and the observed impact on output quality. This makes it immediately clear to team members why certain instruction lines were added or changed. Before a change to a shared prompt is finalized in the library's main branch, it should undergo peer review. Read how to [review prompts as a team](https://community.llmnet.nl/en/prompts-reviewen-in-team) to set up quality assurance and security checks in the development process. Changes to a shared prompt should never be made based on gut feeling or incidental observations. To objectively determine whether a modified instruction actually delivers an improvement over the previous version, quantitative evaluation is required. Run defined [A/B tests on prompts](https://benchmark.llmnet.nl/en/ab-testen-prompts) to verify whether a documented instruction change actually leads to better model output. ## Overview of Prompt Documentation Conventions The table below gives an overview of the minimum requirements a shared prompt file within the development team must meet: Component | Required Standard | Purpose of the Convention | File Name | Kebab-case with functional hierarchy (domein/actie.prompt.md) | Prevents naming conflicts and makes the function of the file immediately recognizable. | Metadata | YAML frontmatter with mandatory fields (id, version, owner, target_model) | Guarantees automatic readability by linter tools and CI/CD pipelines. | Model Configuration | Exact version string from the provider plus temperature and token limit | Guarantees the prompt runs under exactly the same conditions. | Data Hygiene | No credentials, PII, or confidential internal context in text or examples | Prevents data leaks and security risks when distributed within or outside the team. | Input/Output | Make all variables explicit and define a JSON schema for the output | Makes the artifact self-contained and runnable for other developers. | Maintenance | Keep a changelog and periodically validate against new model versions | Prevents 'prompt rot' and safeguards long-term quality. | By strictly applying these conventions from the start of a project, loose instructions transform into reliable, transferable, and maintainable software artifacts that scale seamlessly with the organization.