From d65ec1dfb23aab3f0857698a6f63d7182b6b601c Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Wed, 18 Mar 2026 17:00:49 +0900 Subject: [PATCH] docs: fix links and add reference pages to documentation table Replace making-experts/best-practices links with skills and base-skill across README, docs landing, walkthrough, and rapid-prototyping guide. Remove links to incomplete guides (Rapid Prototyping, Taming Prompt Sprawl) from README. Fix extending-with-tools URL path. Add providers, perstack.toml, events, and API reference links to documentation table. Update rapid-prototyping guide description to match README terminology. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 17 ++++++++++------- docs/getting-started/walkthrough.mdx | 4 ++-- docs/guides/rapid-prototyping.md | 6 +++--- docs/index.mdx | 3 ++- 4 files changed, 17 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 916df9f4..f98e33ca 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

Docs · - Getting Started · + Getting Started · Demo Catalog · Discord · X @@ -287,14 +287,17 @@ Perstack ships a five-layer stack that gives micro-agents everything they need t | Topic | Link | | :--- | :--- | -| Getting started | [Getting Started](https://perstack.ai/docs/getting-started/) | +| Getting started | [Getting Started](https://perstack.ai/docs/getting-started/walkthrough/) | | Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) | -| Expert definitions | [Making Experts](https://perstack.ai/docs/making-experts/) | -| Rapid prototyping | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) | -| Breaking agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) | -| Adding tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) | +| Skills | [Skills](https://perstack.ai/docs/making-experts/skills/) | +| Base skill (built-in tools) | [Base Skill](https://perstack.ai/docs/making-experts/base-skill/) | +| Adding tools via MCP | [Extending with Tools](https://perstack.ai/docs/guides/extending-with-tools/) | | Deployment | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) | -| CLI and API reference | [References](https://perstack.ai/docs/references/cli/) | +| Providers and models | [Providers and Models](https://perstack.ai/docs/references/providers-and-models/) | +| CLI reference | [CLI Reference](https://perstack.ai/docs/references/cli/) | +| `perstack.toml` reference | [perstack.toml Reference](https://perstack.ai/docs/references/perstack-toml/) | +| Events reference | [Events Reference](https://perstack.ai/docs/references/events/) | +| API reference | [API Reference](https://perstack.ai/api/v1/spec) | ## Demo diff --git a/docs/getting-started/walkthrough.mdx b/docs/getting-started/walkthrough.mdx index 0089236e..bae52b22 100644 --- a/docs/getting-started/walkthrough.mdx +++ b/docs/getting-started/walkthrough.mdx @@ -237,8 +237,8 @@ The CLI is for prototyping. The runtime API is for production. Both use the same ## What's next **Build more:** -- [Making Experts](../making-experts/best-practices.md) — full `perstack.toml` guide -- [Skills](../making-experts/skills.md) — MCP integration patterns +- [Skills](../making-experts/skills.md) — MCP tool integration and skill configuration +- [Base Skill](../making-experts/base-skill.md) — built-in tools available to all experts - [Taming Prompt Sprawl](../guides/taming-prompt-sprawl.md) — break monolithic prompts into collaborating experts **Understand the architecture:** diff --git a/docs/guides/rapid-prototyping.md b/docs/guides/rapid-prototyping.md index ca6da3c6..dd04e196 100644 --- a/docs/guides/rapid-prototyping.md +++ b/docs/guides/rapid-prototyping.md @@ -14,7 +14,7 @@ This is backwards. This matters because the agent will keep evolving. Prompts change, capabilities expand, behavior gets refined. If the agent is tangled with your application code, every change risks breaking something unrelated. Keep the brain separate from the body, and both can evolve on their own terms. -This guide uses [Perstack](https://perstack.ai) — a toolkit for agent-first development. In Perstack, agents are called **Experts**: modular micro-agents defined in plain text (`perstack.toml`), executed by a runtime that handles model access, tool orchestration, and state management. Perstack supports multiple LLM providers including Anthropic, OpenAI, and Google. You define what the agent should do; the runtime makes it work. +This guide uses [Perstack](https://perstack.ai) — a containerized harness for agentic apps. In Perstack, agents are called **Experts**: purpose-specific micro-agents defined in TOML (`perstack.toml`), executed by a runtime that handles model access, tool orchestration, and state management. Perstack supports multiple LLM providers including Anthropic, OpenAI, Google, Fireworks, and more. You define what the agent should do; the runtime makes it work. > [!NOTE] > **Prerequisites:** Node.js 22+ and an LLM API key. @@ -130,5 +130,5 @@ At some point, your prototype will need more. The same `perstack.toml` scales ## What's next -- [Making Experts](../making-experts/best-practices.md) — Learn the full Expert definition format -- [Best Practices](../making-experts/best-practices.md) — Design patterns for effective Experts +- [Skills](../making-experts/skills.md) — MCP tool integration and skill configuration +- [Base Skill](../making-experts/base-skill.md) — Built-in tools available to all experts diff --git a/docs/index.mdx b/docs/index.mdx index 2285732e..1c76db00 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -24,7 +24,8 @@ Perstack draws clear boundaries — between your app and the harness, between th ### Build -- [**Making Experts**](/docs/making-experts/best-practices/) — defining experts with skills, delegation, testing, and best practices +- [**Skills**](/docs/making-experts/skills/) — MCP tool integration and skill configuration +- [**Base Skill**](/docs/making-experts/base-skill/) — built-in tools available to all experts - [**Guides**](/docs/guides/rapid-prototyping/) — task-oriented walkthroughs from rapid prototyping to production deployment ### Operate