AI Tools¶

Agentic engineering transitions software development from manually writing routines to orchestrating AI agents that generate them. Similarly to compilers, modern AI tools automate implementation. This elevates the developer's role to system design, specification, and validation.

---
title: Agentic Engineering Workflow
config:
  theme: 'dark'
---
graph TD;
    Human[Human Engineer] -->|Defines Spec & Context| Agent[AI Coding Agent]
    Agent -->|Generates Code| Code[Source Code]
    Human -->|Validates via tests & review| Code
    Agent -.->|Requests Feedback| Human

This document outlines how AI agent context is structured and managed—specifically The Master Prompt, Skills, and Rules — and how Tessl serves as a package manager to distribute and compose this context. Treating context as standardized packages ensures AI agents adhere to unified baseline policies.

Overview¶

Extending the capabilities of AI coding assistants requires structured mechanisms. To manage interaction boundaries, this project utilizes four primary concepts: The Master Prompt, Skills, Rules, and the Model Context Protocol (MCP).

AGENTS.md¶

AGENTS.md is the central entry point and master configuration file for AI assistants within a repository. It establishes the foundational persona, overarching project context, and base operational directives. Serving as the "root" context, it ensures that invoked agents understand the project's macroscopic goals before loading specialized instructions.

Skills¶

While AGENTS.md provides broad repository context, Agent Skills complement it by handling narrow, domain-specific instructions. Typically formatted as lightweight Markdown files (SKILL.md), skills teach an agent how to approach highly specialized, granular tasks—such as preferring lazy evaluation in polars, implementing specific authentication flows, or handling database migrations.

By offloading granular instructions into skills, the master AGENTS.md file remains concise. Skills use progressive disclosure; they are loaded on-demand, keeping agent interactions fast and focused.

📁 skill-name/
├── 📄 SKILL.md        # Required: metadata + instructions
├── 📁 scripts/        # Optional: executable code
├── 📁 references/     # Optional: documentation
├── 📁 assets/         # Optional: templates, resources
└── 📄 ...             # Any additional files or directories

Writing Effective Skills¶

Developing well-crafted skills requires an understanding of how AI coding assistants parse context. Adhering to structured specifications prevents context bloat and unpredictable outputs. Best practices include:

• Keep it Succinct: Avoid lengthy prose. State instructions clearly using direct imperatives to conserve token windows.
• Extract Code to /scripts: Do not embed large scripts directly inside SKILL.md. Place executable code into a sibling scripts/ directory and instruct the agent to run them.
• Isolate References to /references: Move lengthy reference material—such as external API JSON responses or schema documentation—into a dedicated references/ subdirectory, directing the agent to read them only when necessary.

Rules¶

Rules are formalized context files that apply across an entire repository or organization (e.g., .cursorrules or .tessl/RULES.md). While Skills govern specific tasks, Rules represent universal standards, architectural constants, and formatting guidelines. The master AGENTS.md prompt references these rules to enforce collective project conventions.

.agents/¶

Historically, various AI tools assumed proprietary namespaces, such as .gemini/, .claude/, or .cursor/. This fragmentation creates duplication when using multiple AI coding assistants interchangeably.

The universal .agents/ directory provides a model-agnostic structure that allows any agent to discover shared context, rules, and skills:

📁 .agents/
├── 📁 rules/
│   ├── 📄 python-guidelines.md
│   └── 📄 architecture-constraints.md
├── 📁 skills/
│   ├── 📁 deployment/
│   │   ├── 📄 SKILL.md
│   │   ├── 📁 scripts/
│   │   │   └── 📄 deploy-script.sh
│   │   ├── 📁 references/
│   │   │   └── 📄 cloud-api-docs.md
│   │   └── 📁 assets/
│   │       └── 📄 reference-architecture.png
│   └── 📁 database/
│       └── 📄 SKILL.md
└── 📁 workflows/
    ├── 📄 onboarding.md
    └── 📄 release-process.md

Standardizing on .agents/ prevents vendor lock-in and promotes the build-once, run-anywhere philosophy necessary for scalable adoption of AI agents.

Model Context Protocol (MCP)¶

The Model Context Protocol (MCP) is an open standard that enables AI models to connect securely with local and remote data sources. While AGENTS.md, Skills, and Rules are static files containing predefined instructions, MCP acts as a dynamic bridge — allowing agents to query live databases, fetch contemporary internal documentation, or command external system APIs during execution.

When to Use MCP¶

Static context (AGENTS.md, .agents/skills, and .agents/rules) should strictly document relatively immutable domain instructions, architectural constraints, and procedural workflows.

Transition to an MCP Server when the context involves live querying, external state mutation, or is too voluminous to be hardcoded. For example, rather than hardcoding issue details or repository trees into AGENTS.md, the GitHub MCP Server can be executed to let agents read live pull requests or search issues. Similarly, PostgreSQL MCP servers should be used to browse live database schemas instead of statically encoding schema references inside an .agents/skill/ Markdown file.

Artifacts Summary¶

To understand the boundaries between these concepts, refer to the following summary:

The Need for Human Involvement¶

While tools like Tessl, skills, and MCP servers provide automation, they are only as effective as the humans guiding them. As Kubernetes co-founder Brendan Burns states, AI-generated code will become as "invisible as assembly." Developers will spend less time doing line-by-line syntax checks and more time validating behavioral outputs through robust test suites and clear specifications.

This transition shifts the balance of development: generating code requires minimal effort, but blind review remains expensive. As detailed in this project's AI Tool Use Policy, the fundamental rule of agentic engineering is that there must always be a human in the loop.

• Automation of Implementation, Not Judgment: AI expands capabilities; it does not outsource accountability. The human developer remains responsible for the correctness, design, and maintainability of the agent's output.
• Spec-Driven Validation: Because human review of AI-generated pull requests is extractive and costly, modern engineering relies on defining precise, behavior-oriented specifications. If the agent fulfills the spec and passes the test suite, the underlying generated code can be trusted.

The Evolution of Agent Context¶

The maturation of AI coding tools has seen contextual frameworks evolve through several phases:

1. The Introduction Phase: Domain-specific "skills" were popularized to provide agents with targeted instructions, yielding better results than placing large amounts of context into a single prompt.
2. Open-Sourcing and Specifications (AgentSkills): Open standards such as AgentSkills emerged to formalize how skills should be structured, authored, and consumed by disparate agents.
3. Early Registries (skills.sh): Registries like skills.sh were introduced to facilitate skill discovery and fetching via CLI commands.
4. Standardization (rulesync): Managing rules manually across repositories required synchronization tools like rulesync to distribute and enforce agent rules.
5. Enterprise-Ready Context (Tessl): Organizations adopted Tessl as a scalable context enablement platform to provide deterministic supply-chain control, security evaluations, and package-management.

Agent Context as Software Packages¶

Agent skills and context rules were initially distributed as text files vendored directly into a repository. As organizations adopt agents at scale, this approach leads to inconsistent agent context. Context elements are instructions an AI follows — they can execute scripts, access sensitive data, or introduce vulnerabilities.

Publications from JFrog and Pavel's blog on Pixi highlight that skills function similarly to software distributions and face similar challenges:

• Markdown Sprawl: Vendoring skills leads to repository bloat and noisy Git histories.
• Lack of Version Pinning: Without lockfiles, an upstream change to a skill can silently break an agent's workflow.
• Supply Chain Security: Unverified skills might introduce adversarial context or execute malicious commands.
• Enterprise Distribution: Corporate environments require strict access controls, auditing, and secure registries.

The industry is adopting formal package management for agent skills. By treating skills as packages, teams can leverage versioning, lockfiles, and secure registries, ensuring that agents consume verified and predictable context rather than unverified dependencies.

Tessl: Context and Spec-Driven Development¶

Tessl acts as a package manager and registry specifically for agent skills and context.

Tessl operates using Tiles as its fundamental unit of distribution. A tile is a structured container that bundles different forms of context together — such as contextual documentation (lazy pull), organizational rules (eager push), and procedural skills (lazy push).

Using context-management via Tessl allows organizations to:

• Centrally manage and distribute the AGENTS.md master prompt, ensuring all repositories adhere to a unified, compliant baseline before individual skills are invoked.
• Establish a single source of truth for evaluated context tiles across an organization.
• Keep agent behavior consistent and safe without copying Markdown rules across repositories.
• Implement Spec-Driven Development (SDD), where structured, behavior-oriented specifications serve as the primary source of truth, and agents generate the code to match them.

Injecting Managed Rules¶

Maintaining all organizational policies within a single AGENTS.md file can become unwieldy. Rather than forcing developers to manually synchronize rules across repositories, Tessl natively injects centrally managed rules into AGENTS.md by reference.

When configuring a project (e.g., via tessl init), Tessl automatically appends a section marked with <!-- tessl-managed --> that links to .tessl/RULES.md. This allows the master prompt to remain concise while ensuring that invoked agents have access to up-to-date, tile-specific context and overarching organizational constraints.

Scaling for Organizations¶

For organization-wide agentic engineering to succeed, ad-hoc skills must evolve into managed software assets. Tessl functions as a shared repository for agent skills, featuring formal package-management protocols:

• Unified Registry: A centralized hub replaces proprietary folder fragmentation, enabling developers to discover and reuse curated skills.
• Versioning and Pinning: Agents integrate skills via explicit versions or lockfiles (e.g., npx tessl i cisco/software-security@1.2.5), assuring determinism across CI/CD and localized environments.
• Security & Evaluation: Enterprise integration guarantees skills undergo vulnerability scanning, compliance checks, and measurable baseline evaluations prior to broad consumption.
• Interoperability: By maintaining context as formal packages inside the universal .agents/ structure, skills act as universally consumable dependencies.

By adopting tools like Tessl, organizations elevate agent skills from transient prompts into engineered, governed, and distributed software assets.