Darren "Dazbo" Lester for Google Developer Experts

Posted on Apr 2 • Originally published at Medium on Apr 1

Documentation as Context: A Skill to Automate Your Blueprints for the Agentic Era

#projectdocumentation #agentskills #context #gemini

Overview

In this blog I’ll show you an agent skill that empowers your agent with the ability to create awesome documentation for your software project. I’ll cover:

Why documentation is even more important in the agentic coding era.
What an agent skill is.
What the project-documentation skill does and how it works.
How one skill can leverage another.
How you can install the skill and use it yourself.

Documentation: The Superpower Your AI Agents Are Craving

So… here’s the thing. I love documentation. I know, I know. In some circles, admitting that is like saying you enjoy doing your taxes or that you think The Phantom Menace was the best Star Wars film. (It isn’t.) But I’ve talked about this before. For me, documentation isn’t a chore we do at the end of a project. It’s a core part of the architectural and software design process. It’s the superpower that allows us to understand, build, and maintain complex systems without losing our minds.

Building the documentation is arguably the best way to properly comprehend the system we’re building. And the documentation serves as the primary source of knowedge and truth for everyone who has to build, maintain, fix, update and change the solution; now and in the future.

But it’s no longer just about providing knowledge to people. These days we need to inform our agents too.

Why documentation is even more important in the Agentic Era

Today we’re using agents to build and update our solutions; to help us design our solution; to create tests; to implement UIs; to add new features. If we’re going to do that effectively, our agent — whether it’s Gemini Code Assist, Gemini CLI, Google Antigravity, Claude Code or other — needs to fully comprehend the system it’s working on. And, you guessed it… we do that with documentation!

The same documentation serves as critical context for our agents. When we’re “vibe coding” with an agent, we often assume it knows everything just because it’s a genius. But even the smartest architect needs a blueprint. Without clear documentation, your AI agent is essentially flying blind, trying to piece together your architectural intent from a few scattered source code files.

Agents thrive on context. When you provide a well-structured DESIGN.md or a detailed architecture-and-walkthrough.md, you aren't just writing notes for yourself; you're providing the agent with its instruction manual. This allows tools like Gemini CLI to make informed decisions about state management, component hierarchy, and deployment strategies instead of just guessing correctly twice and hallucinating on the third try.

Think of other agentic tools and integrations, like Conductor or Stitch. If you’re using Stitch to build a UI for your application, it needs to know your brand colours, your typography, and components. And Stitch has a preferred way to achieve that: DESIGN.md. If you’re using the Conductor Extension for Gemini CLI, it needs to know your application’s goals, tech stack and architectural boundaries. All this documentation serves as essential context for your agent. It goes much further than just having a GEMINI.md file. A truly effective coding agent needs the deep, specific context found in your architecture documentation, UI design, walkthroughs, and deployment documentation.

But here’s the most important bit: it MUST be maintained and kept in sync. If your code moves on but your docs stay still, your agent will start hallucinating an architecture that no longer exists.

Stale documentation is the quickest way to turn a superpower into a liability.

Agent Skills 101

What is an Agent Skill?

Before we look at my new skill, we should probably talk about what an “Agent Skill” actually is. I’ve written about this before. But to recap:

Skills provide your agent’s model (like Gemini or Claude) just-in-time knowledge for how to do a thing.

When an AI agent needs to do something specific, you can package the domain knowledge for how to do that thing into a skill. The skill can contain instructions, best practices, and sometimes even helper scripts tailored to a particular task.

And you don’t have to tell your agents to use a skill. The agent automatically discovers the skills it has available, and then loads the skill it needs, at the time it needs it. Because it only loads the required skill into context at the point it’s actually required, your model’s context isn’t bloated with irrelevant information. This is good for you, because it makes your agent more efficient, faster, and ultimately cheaper, because it’s consuming fewer tokens.

Anatomy of a Skill

A skill is portable, packaged domain knowledge and instructions for an AI agent, loaded as required.

Romin Irani has written an excellent deep-dive on this topic. But in a nutshell, a skill requires a mandatory SKILL.md file, plus optional additional content.

SKILL.md : The brain of the skill. It contains the YAML metadata — name and description — and the Markdown instructions that guide the agent’s logic. Note that the name and description are the only elements of a skill that are loaded up-front by the agent. The rest is loaded on-demand, as required.
references/ : Where we can include templates, samples or other reference material.
scripts/ : Optional executable code, such as Python or bash scripts.

The beauty of this standard is portability. Because it’s just a directory with a defined structure, you can drop a skill into any agent that supports it (like Gemini CLI or Antigravity) and it just works. I like to think of it as “Capability-as-Code.”

The `project-documentation` Skill

I built a skill called project-documentation. Its mission? To ensure your repo has awesome documentation which never gets stale.

This didn’t start with a blank screen. It started in the middle of a project — my dazbo-portfolio repository. I had spent a fair bit of time getting my documentation up to a reasonable standard. I had a solid README.md, an architecture design and walkthrough document, a testing guide, and a TODO.md full of items.

However, I was finding that I didn’t have a clear line between what was going in the README and what was going in the architecture document. And my UI design documentation had no clear home. I decided it was time to clear these things up, but in a repeatable and codified way. I decided to create an agent skill to do this, such that my documentation can be implemented and maintained in a standard way, for all of my repos going forward.

So, I fired up Gemini CLI and used its built-in skill-creator. Yes — it’s a pre-installed skill that gives Gemini CLI the ability to create new skills! (It’s a bit meta, I know!) I literally asked it to create a new “document-reviewer skill” based on the documentation in my current repository. And I gave it a bit of additional guidance about the files I wanted, including providing a DESIGN.md to capture the UI design for appropriate projects.

The CLI scaffolded my new skill directory, with an initial SKILL.md, and a references folder containing templates for my four core documents. I then hand-edited this skill folder significantly. I refined the logic, evolved the templates, added additional document templates, and provided samples of each document type to be used as the “gold standard”. This ensured that every document the skill touches feels like it was written by the same experienced architect.

The resulting skill folder looks like this:

project-documentation/ # Skill root
├── references/ # Reference content: templates and samples
│   ├── samples/ # Samples - "what good looks like"
|   |   ├── deployment/
|   |   |   └── README.md # Deployment / IaC specific README
|   |   ├── docs/
|   |   |   ├── architecture-and-walkthrough.md # architecture and design
|   |   |   ├── DESIGN.md # UI design
|   |   |   └── testing.md # testing documentation
|   |   └── README.md
│   ├── architecture-and-walkthrough.md.template
│   ├── deployment-README.md.template
│   ├── DESIGN.md.template
│   ├── README.md.template
│   ├── testing.md.template
│   └── TODO.md # TODO checklist / backlog
└── SKILL.md # Description and rules for the skill

The Core Documentation

My skill contains templates and samples for each core documentation type. Let’s look at the actual documents this skill manages. Each has a critical role.

1. `README.md`

This is the developer’s front door. It’s about onboarding.

Focus : Purpose of this repo; overview of the project; developer quickstart; a list of useful project commands.
The Agentic Edge : I’ve structured the template to lead with a “Project Structure” tree. Why? Because an agent needs to know that the backend/ is where the logic lives and deployment/terraform/ is where the infrastructure is provisioned. It’s about giving the agent a map of its new house.
Linking to Other Docs: The README.md also serves as signposting to other key documentation in the repo. So, the README.md can give a few lines to describe the “architecture in-a-nutshell”, but it should then point to the architecture-and-walkthrough.md for the rest of the detail.

For example, the README.md.template looks like this:

# [Project Name]

[Short, compelling description of the project's purpose and what it builds/achieves.]

## Repo Metadata

- Author: [Author]
- Repository: [URL]

## Table of Contents

[Include links to internal page headings.]

## Key Project Documentation

[Provide a table with links to key documentation within the project]

Example:

| Document | Description |
| --- | --- |
| [README.md](README.md) | This file - the developer front door |
| [TODO.md](TODO.md) | TODO list / feature backlog |
| [docs/architecture-and-walkthrough.md](docs/architecture-and-walkthrough.md) | Architecture and walkthrough, including design decisions and data models |
| [docs/DESIGN.md](docs/DESIGN.md) | UI design, visual identity, and frontend UI components |
| [docs/testing.md](docs/testing.md) | Testing docs, including descriptions of all tests |
| [deployment/README.md](deployment/README.md) | Deployment guidance, including Terraform, and CI/CD |
| [GEMINI.md](GEMINI.md) | Guidance for Gemini or other LLMs |

## Key Links

[Bullet list of links to key material, API references, related blogs, etc]

## Project Structure

[This is a sample representation. Check the actual repository to determine the structure. Shows directories first.]

Example:

```text
[Project Root]/
├── deployment/ # Infrastructure and deployment scripts
│   ├── terraform/ # Terraform configuration
│   └── README.md # Deployment documentation
├── docs/ # Documentation
├── app/ # Backend code
├── frontend/ # Frontend code
├── tests/ # Unit, integration, and load tests
│   ├── unit/ # Unit tests
│   └── integration/ # Integration tests
├── .env.template # .env template file
├── pyproject.toml # Project Python dependencies and configuration
├── README.md # This file
└── TODO.md # TODO list
```

## Architecture and Tech Stack - at a Glance

[Brief summary of the key technologies used and the overall architecture. Point to the `architecture-and-walkthrough.md` for further details.]

## Quick Start: Working With This Repo

[Provide details on how to setup and run locally. If deployment instructions are in deployment.md, then simply reference it, as required. This section should include:
- any APIs that must be enabled (e.g. for a project using Google Cloud)
- any APIs keys required
- any environment configuration
- any roles that are needed
- any service accounts that are required ]

Optional sub-sections include:

### Prerequisites

[A list of tools required to work with this repo, e.g. `uv`, `gcloud`, `terraform`]

### One-Time Setup

[E.g. project creation, API enablement]

### Per Dev Session

[E.g. running any scripts to setup dev environment; loading of any env vars]

## Useful Commands

[In a table, list useful commands, scripts and tools. E.g. any make commands or setup bash scripts.]

2. `TODO.md`

I like to use a checkmark list to track backlog items for my project, and what I’ve completed.

3. `docs/architecture-and-walkthrough.md`

This is the architecture blueprint. Here we capture:

The software components in the solution
The design decisions and their associated rationale
Key user journeys through the system.

Here’s the sample file:

4. `docs/DESIGN.md` (Visual & UX)

This is about the UI look-and-feel. I.e. branding, visual identity, colour schemes, UX components. It’s also how our agent can provide crucial information to Stitch when creating UI mockups or iterating on the UI.

For example, the DESIGN.md.template looks like this:

# Visual Design and UX Guidelines

This document serves as the single source of truth for the visual identity and user experience.

## Visual Identity

* **Typography** : [Primary font, e.g., Inter]
* **Color Palette** : [Description of CSS variables and theme]
* **Aesthetics** : [List key styles, e.g., Glassmorphism, Material Design]

## Visual Effects

[Detail specific CSS and visual effects used across the application.]

## Frontend Components

* **[Component Name]**: [Purpose and responsive behavior]

## Development CLI UX

[Detail console visual feedback, e.g., progress bars, rich console output.]

And here’s the associated sample file:

# Design and UX Guide

This document defines the visual identity, frontend user interface components, and command-line experience for the **`dazbo-portfolio`** application.

## Visual Identity

The portfolio follows a high-contrast, premium aesthetic branded as the **"Midnight" Theme** , a refined Material 3-inspired design.

* **Typography** :
* **Main stack** : `'Inter'`, `'Roboto'`, sans-serif.
* **Weights** : 400 (Regular), 500 (Medium/Active Links), 600 (Semi-Bold), 700 (Bold/Titles).
* **Rendering** : Optimized legibility with `-webkit-font-smoothing: antialiased`.
* **Color Palette** :
* **Background** : `#000000` (Pure Black).
* **Surface/Cards** : `#FFFFFF` (White).
* **Primary Accent** : `#6200EE` (Purple).
* **Secondary/Action** : `#03DAC6` (Teal).
* **Branding Accent** : `#BB86FC` (Light Purple).
* **Elevation** : Three distinct shadow levels (`--md-sys-elevation-1` through `3`) provide depth and interaction feedback for Material surfaces.

## Visual Effects

Key visual patterns that contribute to the premium feel:

### Glassmorphism

A core design pattern using `backdrop-filter: blur(10px)` and semi-transparent backgrounds:

* **`.btn-glass`** : Transparent buttons with white borders and subtle hover glows.
* **`.glass-card`** : Low-opacity containers for markdown content and background elements.
* **`.glass-tag`** : High-contrast, blurred labels used for technology tags.

### Premium Interactions

* **Custom Scrollbars** : Minimalist dark-themed scrollbars with smooth rounded thumbs (`#333` to `#555` on hover).
* **Surface Transitions** : Material cards use a 0.3s ease-in-out transition for elevation shifts and a `translateY(-4px)` lift on hover.

## Frontend Implementation

The frontend is a single-page application (SPA) built with React and Vite. It is designed to be responsive, performant, and visually consistent with the Material Design system.

### Key Components

* **`MainLayout`** : The top-level wrapper for all pages. It includes the `AppNavbar` (top), `Footer` (bottom), and the `ChatWidget`.
* **`ShowcaseCarousel`** : A reusable component for displaying collections of items (blogs, projects, etc.).
* **Responsiveness** : On mobile, it displays 1 item per slide. On desktop, it displays a grid of 3 items per slide.
* **Navigation** : Includes custom-styled solid black "Previous" and "Next" controls with white borders and indicators.
* **`ProjectCarousel`** : Specifically configured to sort GitHub projects, prioritising those updated within the last 45 days (must have >0 stars) to highlight active work, followed by a fallback sort based on star count.
* **`ChatWidget`** : A floating action button (FAB) that expands into a chat interface. It currently serves as a shell for future agent integration.
* **`AboutPage`** : A dedicated page for the professional profile, rendering Markdown content from Firestore with a glassmorphic UI design.

### Markdown Rendering (UX)

The application handles Markdown content from Firestore with a focus on professional presentation:

* **Premium Blockquotes** : Features a left-border accent (`--md-sys-color-primary`), glassmorphic background, and distinct attribution styling (uppercase, semi-bold).
* **Glass Tags** : Inline code is rendered as high-readability glassmorphic tags to visually set apart technical terms.

### Development Workflow

There are two primary ways to run the application locally:

#### 1. Process Mode (Rapid Frontend/Backend Iteration)

Ideal for daily development with hot-reloading.

1. **Start the Backend** : `make local-backend` (port 8000).
2. **Start the Frontend** : `make react-ui` (port 5173).
3. **Access** : `http://localhost:5173`. Requests to `/api/*` are proxied to port 8000.

#### 2. Container Mode (Production Parity)

Ideal for verifying the final build and deployment configuration.

1. **Build** : `make docker-build`.
2. **Run** : `make docker-run`.
3. **Access** : `http://localhost:8080`. Port 8080 serves both the UI and the API.

## Command-Line Experience (CLI UX)

The CLI tools are designed for immediate visual feedback and clarity when managing content.

### Console UX with Rich

The application uses the `rich` library to enhance the CLI experience with spinners, progress bars, and thread-safe logging. This ensures a clean and readable output during long-running ingestion tasks.

5. `docs/testing.md`

We need our code to be testable and verified. Here we capture:

The testing frameworks in use.
Mocking strategies.
How to execute the tests, including any manual verification tests.
A summary of all the tests in the project.

Here’s the sample testing.md:

# Unified Testing Documentation

This document serves as the comprehensive guide for testing strategy, execution, and manual verification for the Rickbot-ADK project.

## Table of Contents

0. [General Testing Principles](#general-testing-principles)
- [CI-Aware Execution](#ci-aware-execution)
- [Running Tests (All Commands)](#running-tests-all-commands)
1. [Backend Testing Strategy](#backend-testing-strategy)
- [Test Summary](#test-summary)
- [Configuration & Test Mode](#configuration--test-mode)
2. [Frontend Testing Strategy](#frontend-testing-strategy)
- [Stack Overview](#stack-overview)
- [Writing Frontend Tests](#writing-frontend-tests)
3. [Authentication & Session Management](#authentication--session-management)
- [Retrieving Bearer Tokens](#retrieving-bearer-tokens)
- [Mock Tokens](#mock-tokens)
4. [Manual API Verification](#manual-api-verification)
- [Using Curl with Authentication](#using-curl-with-authentication)
- [Artifact Retrieval](#artifact-retrieval)

---

## General Testing Principles

Regardless of the component being tested (Backend or Frontend), the following principles apply:

### CI-Aware Execution

All test runners should be aware of the `CI` environment variable. When `CI=true`:

- Test runners must execute once and exit (no watch mode).
- Interactive prompts must be suppressed.
- Output should be optimized for logs.

### Running Tests (All Commands)

#### Backend (Python)

- Run unit tests: `make test`
- Run all tests (Unit + Integration): `make test-all`
- Run specific test file: `uv run pytest -v -s src/tests/unit/test_config.py`

#### Frontend (React/Next.js)

- Run all tests: `make test-ui` (or `cd src/nextjs_fe && npm test`)
- Run in watch mode: `cd src/nextjs_fe && npm run test:watch`

---

## Backend Testing Strategy

This section covers the strategy for testing the Python backend components of the Rickbot-ADK project.

### Test Summary

The following table summarizes the existing backend tests, their category, and their purpose:

| File | Category | Purpose |
| :--- | :--- | :--- |
| `test_config.py` | Unit | Verifies the loading and validation of application configuration from `config.py`. |
| `test_create_auth_secrets.py` | Unit | Tests the utility script for creating Streamlit authentication secrets. |
| `test_logging_utils.py` | Unit | Validates the setup and functionality of the logging utilities. |
| `test_personality.py` | Unit | Tests the `Personality` data class and ensures personalities are loaded correctly from the YAML configuration. |
| `test_auth_models.py` | Unit | Tests the `AuthUser` Pydantic model for user authentication data. |
| `test_auth_dependency.py` | Unit | Verifies the token validation logic, including mock token support. |
| `test_api_auth.py` | Unit | Tests authentication endpoints and logic within the API. |
| `test_api_fastapi.py` | Unit | Tests core FastAPI application configuration and middleware. |
| `test_api_personas.py` | Unit | Detailed unit tests for the `/personas` endpoint logic. |
| `test_access_control_services.py` | Unit | Tests the retrieval of user roles and persona requirements from Firestore (mocked). |
| `test_access_control_middleware.py` | Unit | Verifies that the `PersonaAccessMiddleware` correctly enforces RBAC and returns structured errors. |
| `test_artifacts.py` | Integration | Verifies that file uploads are saved as ADK Artifacts and can be retrieved via the `/artifacts` endpoint. |
| `test_tool_status.py` | Integration | Verifies that tool call events are correctly emitted by the `/chat_stream` endpoint. |
| `test_api.py` | Integration | Contains tests for the FastAPI `/chat` endpoint. Includes a mocked test for basic success and a true integration test for multi-turn conversation memory. |
| `test_personalities.py` | Integration | Runs a simple query against every available agent personality to ensure each one can be loaded and can respond. |
| `test_rickbot_agent_multiturn.py` | Integration | Verifies the agent's conversation memory by directly using the ADK `Runner` for a two-turn conversation. |
| `test_server_e2e.py` | Integration (E2E) | Provides an end-to-end test by starting the actual FastAPI server via `uvicorn` and testing endpoints like `/chat` and `/chat_stream`. |
| `test_gcs_integration.py` | Integration | Mocks GCS environment and client to ensure `GcsArtifactService` is correctly instantiated and utilized when `ARTIFACT_BUCKET` is set. |

### Configuration & Test Mode

To ensure tests can run without requiring production secrets (specifically those for "Dazbo" or other protected personalities), the test suite runs in **Test Mode**.

- **Mechanism** : The `RICKBOT_TEST_MODE` environment variable is set to `"true"` automatically for all tests via `src/tests/conftest.py`.
- **Behavior** : When `RICKBOT_TEST_MODE` is active, if the application fails to retrieve a system prompt secret from Google Secret Manager, it falls back to a dummy system prompt (`"You are {name}. (DUMMY PROMPT FOR TESTING)"`) instead of raising a `ValueError`.
- **Purpose** : This ensures that unit and integration tests (such as `test_personalities.py`) do not crash due to missing local secrets or permissions, while still allowing the actual logic to be exercised.

#### Conftest

The `src/tests/conftest.py` file is a global Pytest configuration that:

1. Sets `RICKBOT_TEST_MODE=true` for the entire test session.
2. Ensures consistent environment variables are available for both unit and integration tests.

---

## Frontend Testing Strategy

The Rickbot-ADK frontend is built with Next.js and is tested using a modern React testing stack.

### Stack Overview

- **Jest** : The primary test runner and assertion library.
- **React Testing Library (RTL)**: Used for rendering components and interacting with them in a way that mimics user behavior.
- **jest-environment-jsdom** : Provides a browser-like environment for testing React components.
- **next/jest** : Official Next.js integration for Jest, which automatically configures transform and environment settings.

### Writing Frontend Tests

Frontend tests are located in `src/nextjs_fe/__tests__/`. We follow these conventions:

- **Component Tests** : Focused on individual UI components (e.g., `AuthButton.test.tsx`).
- **Page Tests** : Focused on full pages and their accessibility (e.g., `Privacy.test.tsx`).
- **User-Centric Testing** : Prefer testing behavior (what the user sees and does) over implementation details (internal state or props).

---

## Authentication & Session Management

The Rickbot-ADK backend requires a valid Bearer token for most operations. This section explains how to obtain a token for manual testing and how to use mock tokens in development.

### Retrieving Bearer Tokens

The easiest way to obtain a valid Bearer token for an active session is using the browser's Developer Tools.

#### From the Network Tab (Recommended)

1. Open the Rickbot UI in your browser and sign in.
2. Open **Developer Tools** (F12 or `Cmd+Opt+I` on Mac).
3. Select the **Network** tab.
4. Refresh the page or perform an action (like changing the personality or sending a message).
5. Look for a request to the backend API (e.g., `personas`, `chat_stream`).
6. Click on the request and go to the **Headers** tab.
7. Locate the **Request Headers** section and find the `Authorization` header.
8. Copy the value after `Bearer ` (e.g., the long string of characters).

#### From the Console

If you have access to the source code and want to quickly log the token, you can temporarily add `console.log(session.idToken)` in `Chat.tsx` and view it in the **Console** tab.

### Mock Tokens

For local development and testing, the backend supports a "Mock Token" format that bypasses Google/GitHub OAuth verification.

- **Format** : `mock:unique_id:email:display_name`
- **Example** : `mock:123:tester@example.com:TesterUser`

To use a mock token:

1. Ensure the backend is NOT in production mode (or `RICKBOT_TEST_MODE=true`).
2. Use the mock string directly in your `Authorization` header:

    ```bash
    Authorization: Bearer mock:123:tester@example.com:TesterUser
    ```

**Note** : Mock tokens are only accepted if the backend's `verify_token` logic allows them, which is typically enabled in development environments.

## Manual API Verification

Once you have obtained a Bearer token, you can use `curl` to manually interact with the API. It is recommended to store your token in an environment variable.

```bash
export AUTH_TOKEN="your_retrieved_token_here"
# OR use a mock token
export AUTH_TOKEN="mock:123:tester@example.com:TesterUser"
```

### Using Curl with Authentication

#### List Available Personas

```bash
curl -X GET "http://localhost:8000/personas" \
-H "Authorization: Bearer $AUTH_TOKEN"
```

#### Send a Message (Single-Turn)

```bash
curl -X POST "http://localhost:8000/chat" \
-H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: multipart/form-data" \
-F "prompt=Hello Rick!" \
-F "personality=Rick" \
-F "user_id=test_user"
```

#### Stream a Conversation

```bash
curl -X POST "http://localhost:8000/chat_stream" \
-H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: multipart/form-data" \
-F "prompt=Tell me a joke" \
-F "personality=Rick" \
-F "user_id=test_user"
```

### Artifact Retrieval

One of the primary uses for manual `curl` testing is verifying ADK Artifacts (files, images, videos) that the agent might have generated or received.

#### Download/Retrieve an Artifact

Replace `<FILENAME>` with the actual filename of the artifact (e.g., `image_123.png`).

```bash
curl -X GET "http://localhost:8000/artifacts/<FILENAME>" \
-H "Authorization: Bearer $AUTH_TOKEN" \
--output downloaded_artifact.png
```

**Note** : You can find artifact filenames in the JSON response or stream data from the `/chat` or `/chat_stream` endpoints.

### Access Control (RBAC) Verification

To manually verify that persona access restrictions are working correctly, use the following `curl` commands with different mock users.

#### 1. Verify Restricted Access (Standard User)

Attempt to access a 'supporter'-tier persona (e.g., Yasmin) with a 'standard' mock user.

```bash
curl -v -X POST http://localhost:8000/chat \
-F "personality=Yasmin" \
-F "prompt=hi" \
-H "Authorization: Bearer mock:1:user@example.com:User"
```

**Expected Outcome** : `403 Forbidden` with a JSON body containing `"error_code": "UPGRADE_REQUIRED"`.

#### 2. Verify Allowed Access (Supporter User)

Access a 'supporter'-tier persona (e.g., Dazbo) with a mock user who has the 'supporter' role seeded in Firestore.

```bash
curl -v -X POST http://localhost:8000/chat \
-F "personality=Dazbo" \
-F "prompt=hi" \
-H "Authorization: Bearer mock:derailed-dash:derailed.dash@gmail.com:Dazbo"
```

**Expected Outcome** : `200 OK` with a valid agent response.

6. `deployment/README.md`

This one is about deployment and infrastructure. It includes such things as:

Options for how the application can be deployed, such as bash scripts and/or Terraform.
Roles and permissions.
CI/CD pipelines, including any variable propagation.

Triggers

The other secret sauce of the skill is its triggers. It is crucial to give your agent super-clear instructions as to when your skill should be activated. Let’s take a look at the first few lines of my SKILL.md:

---
name: project-documentation
description: Creates, maintains, and synchronizes core project documentation (README, TODO, DESIGN, Architecture, Testing, Deployment). Use when the user needs to write, update, or structure project documentation based on codebase changes.
---

# Project Documentation Skill

This skill provides a comprehensive framework for the creation and maintenance of high-quality, professional technical documentation for any software project or repository.

## Triggers

This skill should be triggered whenever:

- The user requests to create or review documentation.
- The user adds / changes / deletes functionality, or makes significant changes to the codebase.
- The user makes any changes to testing.
- The user makes any changes to deployment.

The top block is the YAML frontmatter, where we define the skill name and description. This description must be clear enough to inform your agent as to when this skill will be relevant. Remember that pre-activation, the agent only has the content of the description to go on.

Lower in the SKILL.md file I’ve gone further and added some explicit guidance as to when to trigger this skill. And finally, I’ve also added further explicit triggering rules against each document type in the skill. For example, for our UI DESIGN.md:

### 3. `docs/DESIGN.md` (Visual & UX)

* **Focus** : Visual identity, UX components, and design tokens.
* **Template** : [design.md.template](references/design.md.template)
* **Sample** : [docs/DESIGN.md](references/samples/docs/DESIGN.md)
* **Key Sections** : Visual Identity (Typography, Colours), Visual Effects (e.g. Glassmorphism), Frontend Components (Layout, Carousel, Widget, etc), CLI UX (if present).
* **Triggers** :
- When implementing a UI framework (e.g. React, Vue, Angular, Svelte, etc).
- When adding or changing any UI components.
- Modifying visuals or style, e.g. modifying `index.css` global styles.

Also note how each document section points to the relevant template, and the relevant sample file. To see the full SKILL.md, feel free to check out the repo.

Calling Other Skills

I’m a big believer in the single responsibility principle. You know… do one thing and do it well. If another skill exists that provides capability we want to leverage, don’t duplicate it. Just call it! That’s why my project-documentation skill automatically checks if you have the technical-writer skill installed.

This is great skill from the very popular awesome-llm-apps repo. If this skill is present then my skill leverages it to improve documentation quality. But if the skill is missing, my skill offers to install it, and knows how to install it.

Here’s the relevant section from my SKILL.md:

## Technical Writer Skill Synergy

The `technical-writer` skill improves the quality of your documentation review and creation. If you are performing any documentation tasks (e.g. creation or updates to README, TODO, DESIGN, Architecture, Testing, Deployment) and the `technical-writer` skill is not available in your current skills toolset:

1. **Check for existence** : Use `npx skills list` (project scope) and `npx skills ls -g` (global scope) to verify if it is missing.
2. **Recommend** : If not yet installed, inform the user that the `technical-writer` skill provides advanced formatting and style guidance. Offer to install it.
3. **Install** : If the user agrees, install the skill for them using this command: `npx skills add https://github.com/shubhamsaboo/awesome-llm-apps --skill technical-writer -g -y`
4. **Collaborate** : Once installed, load this skill and leverage it for documentation tasks.

It’s important to note that the technical-writer skill isn’t essential and my skill works fine without it. But you get the best results when you combine them.

Agentic Best Practices and Lessons Learned

If you’re thinking about building your own skills, here are some core principles to follow:

1. Progressive Disclosure

Don’t overwhelm the agent with information it doesn’t need yet. Your name and description are the "hook". Keep them descriptive so the agent knows when to pull the skill off the shelf. Once it's loaded, the SKILL.md should provide the deep logic, and the references/ should provide the raw data and “what good looks like.”

2. Assume Your Model Knows the Basics

Your agent already knows how to write Markdown. Instead, focus your instructions on your specific standards. Use your references/ to provide the "Gold Standard" examples that calibrate the agent's output.

3. Self-Contained Portability

A great skill should be a “black box” of capability. Someone should be able to drop your skill folder into their project and have it work instantly.

4. Very Clear Instructions

My first iteration of this skill sometimes failed to offer to install the technical-writer skill. I needed to add this extra section to enforce a much more repeatable workflow:

## Mandatory Initialization

Before performing ANY documentation task, you MUST check for the presence of the `technical-writer` skill, by following the guidance in the `Technical Writer Skill Synergy` section below.

Installing and Using the Skill

I recommend you install this skill and make use of it for all your future projects! To install, just run this:

# Install the project-documentation skill globally
npx skills add derailed-dash/dazbo-agent-skills --skill project-documentation -g -y

Once installed, it will automatically activate whenever you’re working in a repository that needs documentation maintenance. Give it a go. Install the skill and then tell your agent:

“Please ensure I have good documentation for this project.”

Or simply:

“Review my documentation.”

You can find the skill and its source code over at my GitHub repo: derailed-dash/dazbo-agent-skills. If you find it useful, please give the repo a star! It helps me know people are actually using these tools, and it gives me motivation to keep open sourcing my stuff and writing these blogs.

Wrap Up

The project-documentation skill isn't just about making your repo look pretty. It's about building a robust, AI-ready foundation for your software. By codifying documentation standards into a portable agent skill, we’ve ensured that both humans and and AI assistants have the context needed to build, scale, and maintain our projects effectively and consistently.

Whether you’re using Gemini, Claude, or any other agentic tool, remember that documentation is context. The better your docs, the smarter your agent. So, take the leap — install the skill, refine your templates, and start treating your documentation as the high-value architectural asset it truly is. Your future self (and your agent) will thank you.

You Know What To Do!

Please share this with anyone that you think will be interested. It might help them, and it really helps me!
Please give me 50 claps! (Just hold down the clap button.)
Feel free to leave a comment 💬.
Follow and subscribe, so you don’t miss my content.

DEV Community

Documentation as Context: A Skill to Automate Your Blueprints for the Agentic Era

Overview

Documentation: The Superpower Your AI Agents Are Craving

Why documentation is even more important in the Agentic Era

Agent Skills 101

What is an Agent Skill?

Anatomy of a Skill

The `project-documentation` Skill

The Core Documentation

1. `README.md`

2. `TODO.md`

3. `docs/architecture-and-walkthrough.md`

4. `docs/DESIGN.md` (Visual & UX)

5. `docs/testing.md`

6. `deployment/README.md`

Triggers

Calling Other Skills

Agentic Best Practices and Lessons Learned

1. Progressive Disclosure

2. Assume Your Model Knows the Basics

3. Self-Contained Portability

4. Very Clear Instructions

Installing and Using the Skill

Wrap Up

You Know What To Do!

Useful Links and References

Top comments (0)

Overview

Documentation: The Superpower Your AI Agents Are Craving

Why documentation is even more important in the Agentic Era

Agent Skills 101

What is an Agent Skill?

Anatomy of a Skill

The project-documentation Skill

The Core Documentation

1. README.md

2. TODO.md

3. docs/architecture-and-walkthrough.md

4. docs/DESIGN.md (Visual & UX)

5. docs/testing.md

6. deployment/README.md

Triggers

Calling Other Skills

Agentic Best Practices and Lessons Learned

1. Progressive Disclosure

2. Assume Your Model Knows the Basics

3. Self-Contained Portability

4. Very Clear Instructions

Installing and Using the Skill

Wrap Up

You Know What To Do!

Useful Links and References

The `project-documentation` Skill

1. `README.md`

2. `TODO.md`

3. `docs/architecture-and-walkthrough.md`

4. `docs/DESIGN.md` (Visual & UX)

5. `docs/testing.md`

6. `deployment/README.md`