Building a NuGet Package That Includes Documentation for AI Coding Tools

AI coding tools can generate useful code only when they have enough context about the project, APIs, coding standards, and development practices they are expected to follow.

For a team building its own libraries or internal APIs, one practical approach is to package that guidance alongside the software using NuGet.

A NuGet package does not have to contain only compiled .NET assemblies. It can also carry Markdown files, examples, configuration guidance, API rules, and other documentation that can be made available to developers and AI-assisted development workflows.

This approach is useful when the same documentation needs to be distributed across multiple .NET projects.

Instead of manually copying files into every repository, the team can maintain one documentation source, package it, publish a version, and let consuming projects reference that version.

This article shows how to build a NuGet package that contains documentation intended for AI coding tools and how to make the package practical to maintain.

What the Package Should Contain

Before creating the package, decide what information the AI coding workflow actually needs.

A useful package might contain:

Company.AI.Guidance/
├── ai/
│   ├── coding-guidelines.md
│   ├── architecture-rules.md
│   ├── api-patterns.md
│   └── security-rules.md
├── docs/
│   ├── getting-started.md
│   ├── api-usage.md
│   └── troubleshooting.md
├── examples/
│   ├── HttpClientExample.cs
│   └── AuthenticationExample.cs
└── Company.AI.Guidance.nuspec

The exact structure is not fixed.

The important part is that the package should have a clear purpose.

For example:

ai/
    coding-guidelines.md
    architecture-rules.md

can contain concise guidance intended for AI-assisted coding.

Meanwhile:

docs/
    api-usage.md
    troubleshooting.md

can contain more detailed developer documentation.

Create the NuGet Project

If the package only needs to distribute documentation, a standard SDK-style project can be used.

Create a project:

dotnet new classlib -n Company.AI.Guidance

Move into the project directory:

cd Company.AI.Guidance

The generated project will contain a .csproj file.

For a documentation package, you may not need any actual C# classes.

The project can exist primarily as the packaging container.

Configure the Project File

A basic project file can look like this:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>

    <PackageId>Company.AI.Guidance</PackageId>
    <Version>1.0.0</Version>

    <Authors>Company Engineering</Authors>
    <Description>
      Development guidance and documentation for AI-assisted coding.
    </Description>

    <PackageTags>ai;documentation;developer-tools</PackageTags>

    <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
  </PropertyGroup>

</Project>

The PackageId determines the name developers use when adding the package.

For example:

dotnet add package Company.AI.Guidance

Add the Documentation Files

Create the documentation directories:

ai/
docs/
examples/

Then add Markdown files.

For example:

ai/coding-guidelines.md
ai/architecture-rules.md
ai/security-rules.md
docs/api-usage.md
docs/troubleshooting.md

A simple coding guidance file might look like this:

# Coding Guidelines

Use async APIs for network and database operations.

Prefer dependency injection over manually creating service dependencies.

Do not log credentials, access tokens, or sensitive configuration values.

Use cancellation tokens for long-running asynchronous operations.

Prefer existing project abstractions over creating duplicate implementations.

Keep these instructions specific.

An AI coding tool gets more value from concrete project rules than from generic statements such as:

Write clean code.

Include Files in the NuGet Package

By default, files that are not compiled source files may not automatically be placed in the package.

You can explicitly configure them.

For example:

<ItemGroup>
  <None Include="ai\**\*"
        Pack="true"
        PackagePath="ai" />

  <None Include="docs\**\*"
        Pack="true"
        PackagePath="docs" />

  <None Include="examples\**\*"
        Pack="true"
        PackagePath="examples" />
</ItemGroup>

This tells the NuGet pack operation to include the specified files.

The resulting package will contain directories such as:

ai/
docs/
examples/

Choose a Predictable Package Structure

Avoid changing the package layout between versions without a clear reason.

For example, if version 1.0 contains:

ai/coding-guidelines.md

and version 1.1 suddenly moves the file to:

documentation/ai-guidelines.md

consuming workflows may break if they depend on the original path.

A stable structure is easier to automate.

For example:

ai/
    coding-guidelines.md
    architecture-rules.md
    security-rules.md

docs/
    api-usage.md
    troubleshooting.md

examples/
    ...

Keep the package layout predictable as the documentation grows.

Add Code Examples

AI coding tools need more than rules.

Examples demonstrate how the project expects code to be written.

For example:

public async Task<Customer?> GetCustomerAsync(
    Guid customerId,
    CancellationToken cancellationToken)
{
    return await customerClient.GetCustomerAsync(
        customerId,
        cancellationToken);
}

The documentation can explain why this pattern is preferred:

# Customer API Example

Use the asynchronous API for HTTP requests.

Always pass the CancellationToken provided by the calling operation.

Avoid creating a new HttpClient for every request.

Prefer the application's registered CustomerClient.

This gives the AI workflow both an example and the rules behind it.

Add Architecture Rules

Architecture documentation can help prevent generated code from introducing patterns that conflict with the existing application.

For example:

# Architecture Rules

Controllers should not contain database access code.

Use application services for business operations.

Use repositories only where the project already defines a repository abstraction.

External HTTP calls should be made through registered clients.

Business logic should not depend directly on ASP.NET Core infrastructure.

These rules are more useful than a generic statement such as “follow clean architecture.”

The package should describe the actual conventions used by the team.

Add Security Rules

Security guidance is another useful part of an AI documentation package.

For example:

# Security Rules

Never write passwords or access tokens to logs.

Do not hard-code credentials.

Use the application's existing authentication service.

Validate externally supplied input.

Do not disable TLS certificate validation in production code.

This can help developers avoid repeatedly making the same security mistakes when using AI-generated code.

Pack the NuGet Package

Once the project structure is ready, create the package:

dotnet pack -c Release

The package will normally be created under:

bin/Release/

For example:

Company.AI.Guidance.1.0.0.nupkg

You can inspect the package contents before publishing it.

This is an important step because a successful dotnet pack command does not guarantee that every intended documentation file was included.

Inspect the Generated Package

A .nupkg file is a ZIP-based package.

You can inspect its contents with standard archive tools.

You should see something similar to:

Company.AI.Guidance.1.0.0.nupkg
│
├── ai/
│   ├── coding-guidelines.md
│   ├── architecture-rules.md
│   └── security-rules.md
│
├── docs/
│   ├── api-usage.md
│   └── troubleshooting.md
│
├── examples/
│   └── HttpClientExample.cs
│
└── Company.AI.Guidance.nuspec

If the ai or docs directories are missing, check the PackagePath and Pack settings in the project file.

Test the Package Locally

Do not immediately publish the package to an internal or public feed.

Test it locally first.

Create a local package directory:

C:\NuGetPackages

Then add the directory as a package source:

dotnet nuget add source C:\NuGetPackages \
    --name LocalPackages

Copy the generated .nupkg file into the directory.

You can then consume the package from another test project.

This provides a safe way to verify the package before making it available to other developers.

Consume the Documentation Package

Add the package to a test project:

dotnet add package Company.AI.Guidance \
    --version 1.0.0

Restore the project:

dotnet restore

The package is now part of the project's dependency graph.

However, there is an important distinction.

Installing a package does not automatically mean that an AI coding tool will read every Markdown file inside it.

The package provides a reliable distribution mechanism. The consuming AI workflow still needs to know how those files are discovered and used.

That separation is important when designing the overall solution.

Make Documentation Discoverable

The documentation package should have a predictable location.

For example:

project/
├── src/
├── tests/
└── .ai/

A consuming setup may copy or expose the relevant package files into a project-specific documentation location.

For example:

project/
├── .ai/
│   ├── coding-guidelines.md
│   ├── architecture-rules.md
│   └── security-rules.md
├── src/
└── tests/

The exact mechanism depends on the AI coding tool being used.

The important design principle is:

NuGet
   ↓
Versioned documentation
   ↓
Project documentation location
   ↓
AI coding workflow

NuGet solves distribution and versioning. The AI tool's supported context mechanism determines how the documentation is consumed.

Automate Documentation Placement When Needed

If developers must manually copy the files after every package update, the workflow becomes difficult to maintain.

Automation can extract or synchronize the required documentation.

A CI/CD step might:

Restore NuGet package
        ↓
Locate AI documentation
        ↓
Copy approved files
        ↓
Validate project rules
        ↓
Run build/tests

The exact implementation depends on the project's development environment.

For larger teams, automation is preferable to asking every developer to manually maintain AI context files.

Add Package Metadata

A production package should have useful metadata.

For example:

<PropertyGroup>
  <PackageId>Company.AI.Guidance</PackageId>
  <Version>1.0.0</Version>
  <Authors>Company Engineering</Authors>
  <Description>
    Versioned coding and architecture guidance for AI-assisted development.
  </Description>

  <PackageTags>
    ai;documentation;coding-guidelines;developer-tools
  </PackageTags>

  <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
</PropertyGroup>

Metadata becomes particularly important when an organization has many internal packages.

Developers should be able to identify what the package contains without opening the package itself.

Version the Package Carefully

Documentation changes should be versioned.

For example:

1.0.0
Initial AI coding guidance

1.1.0
Added API usage patterns

1.2.0
Added security rules

2.0.0
Reorganized documentation and changed package structure

If consuming automation depends on specific paths, a package structure change may be significant even if no runtime code changed.

Document breaking changes in the package release notes.

Separate Documentation Changes From Application Code

It can be useful to keep the documentation package in its own repository:

Company.AI.Guidance
        |
        +-- ai/
        +-- docs/
        +-- examples/
        +-- Company.AI.Guidance.csproj

This provides a clear ownership boundary.

Another option is to maintain the documentation beside the library or API it describes.

For example:

Company.Customer.Api
        |
        +-- src/
        +-- tests/
        +-- docs/
        +-- ai/

The best choice depends on how frequently the documentation changes and who owns it.

Keep API Documentation and AI Guidance Separate

Not every piece of documentation should be sent to an AI coding workflow.

Consider separating:

docs/
    complete API reference
    troubleshooting
    architecture documentation

ai/
    coding rules
    preferred patterns
    security constraints
    common mistakes

This keeps AI-oriented context smaller and easier to maintain.

An AI tool does not necessarily need every historical design document or every page of API reference material for a simple coding task.

Validate Documentation in CI

The package build should include documentation validation.

Useful checks include:

Required files exist
Markdown is valid
Internal links work
Code examples compile where practical
API version references are correct
Deprecated methods are not recommended
Package structure has not changed unexpectedly

For example, a simple CI validation can check that required files exist:

ai/coding-guidelines.md
ai/architecture-rules.md
ai/security-rules.md

If one is accidentally removed, the package build can fail instead of publishing an incomplete documentation package.

Test Code Examples

Code examples should not become outdated.

Suppose the documentation contains:

var result = await client.GetCustomerAsync(id);

If GetCustomerAsync is renamed or its parameters change, the documentation can become misleading.

For important examples, create executable tests.

One approach is to maintain sample projects:

examples/
    CustomerApiExample/
    AuthenticationExample/

The CI pipeline can build those projects.

This gives the team an additional check that documentation examples still match the actual API.

Avoid Including Sensitive Information

Documentation packages may be distributed to many projects.

Never include:

API keys
Passwords
Access tokens
Production connection strings
Private certificates
Internal secrets

Instead, document the configuration pattern.

For example:

Use the CUSTOMER_API_URL environment variable.

Authentication credentials must be supplied through the application's
approved secret-management mechanism.

Documentation should teach the configuration process without exposing secrets.

Common Mistakes

Assuming NuGet automatically feeds the AI tool

NuGet provides packaging and dependency management.

It does not automatically guarantee that an AI coding tool will discover and use every file inside the package.

You still need a documented mechanism for exposing the relevant files to the AI workflow.

Putting everything into one Markdown file

A huge file containing every rule, API reference, architecture decision, and troubleshooting guide quickly becomes difficult to maintain.

Separate content by purpose.

Packaging documentation without testing it

A package can build successfully while missing files.

Inspect the .nupkg contents before publishing.

Updating documentation without versioning it

If developers cannot identify which documentation version they are using, troubleshooting AI-generated code becomes harder.

Version the package like other engineering dependencies.

Making the documentation too generic

Statements such as:

Write secure code.
Use best practices.
Follow good architecture.

provide little practical value.

Prefer concrete rules:

Do not create HttpClient instances inside controller methods.

Use the registered CustomerApiClient through dependency injection.

Best Practices

Give the documentation package a clear purpose.
Keep AI-specific guidance separate from large reference documents.
Use a predictable package directory structure.
Explicitly include documentation files in the NuGet package.
Version the package using a consistent release policy.
Test the generated .nupkg before publishing.
Validate important code examples through CI.
Automate synchronization with the consuming project where necessary.
Keep secrets out of documentation.
Document how the AI coding workflow discovers the packaged content.
Record breaking changes to documentation paths.
Keep package ownership clear.

Advantages and Disadvantages

Area	Advantages	Considerations
Distribution	Uses an existing .NET package workflow	AI tools still need a way to consume the files
Versioning	Documentation versions are explicit	Package updates require dependency management
Reuse	Multiple projects can use the same package	Projects may require different guidance
Automation	CI can build and publish the package	Initial pipeline setup takes effort
Consistency	Teams receive the same rules and examples	Local modifications can create differences
Maintenance	Central documentation source	Ownership and review are required

Example End-to-End Workflow

A simple implementation can look like this:

Documentation source
        |
        v
Markdown + examples
        |
        v
NuGet project
        |
        v
dotnet pack
        |
        v
Company.AI.Guidance.1.0.0.nupkg
        |
        v
Internal NuGet feed
        |
        v
.NET application
        |
        v
AI documentation location
        |
        v
AI coding workflow

When the guidance changes, release another version:

1.0.0
   ↓
1.1.0
   ↓
1.2.0

Projects can then update the package when they are ready.

Conclusion

A NuGet package can provide a practical and repeatable way to distribute documentation used by AI-assisted development workflows.

The implementation is straightforward: create a package project, organize the documentation, explicitly include the files during packing, validate the generated package, publish it to the appropriate package feed, and establish a reliable way for consuming projects to expose the documentation to their AI coding workflow.

The important part is to treat the documentation as an engineering dependency rather than a collection of files copied between projects.

When the package is versioned, tested, and maintained alongside the software it describes, teams can keep AI coding guidance consistent across multiple .NET applications while avoiding repeated manual documentation updates.