# Development Story Report Skill

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Works with](https://img.shields.io/badge/Works_with-Claude_Code_|_Codex-blue.svg)](#getting-started)
[![Agent Skills](https://img.shields.io/badge/Standard-Agent_Skills-blueviolet.svg)](https://agentskills.io/)
[![Repo](https://img.shields.io/badge/GitHub-fengwang%2Fdevelopment--story--report--skill-181717?logo=github)](https://github.com/fengwang/development-story-report-skill.git)

A cross-platform skill package for generating brief, top-down wrap-up reports after a completed story, session, or workstream. The skill applies **Pyramid Principle** structure to help busy, non-technical readers understand what changed, why it matters, what remains open, and what should happen next.

This repository ships ready-to-use wrappers for **Claude Code** and **Codex**, plus the shared source material and local tooling used to generate and validate them.

---

## Report for This Skill

Check out [our development story](./docs/2026-03-16-leader-development-story-report.md) as a boss -:) It is automatically generated using this very skill.

---

## What's Included

- **Claude Code skill wrapper** in [`claude/development-story-report/`](./claude/development-story-report)
- **Codex skill wrapper** in [`.agents/skills/development-story-report/`](./.agents/skills/development-story-report)
- **Shared source-of-truth skill content** in [`skill-src/`](./skill-src)
- **Builder and validation tooling** in [`src/development_story_report_tooling/`](./src/development_story_report_tooling) and [`scripts/build_skill_wrappers.py`](./scripts/build_skill_wrappers.py)
- **Evaluation prompts** in [`evals/development-story-report-evals.json`](./evals/development-story-report-evals.json)
- **Development history and planning docs** in [`dev-docs/`](./dev-docs)

---

## Why Use This?

### Executive-grade wrap-ups

- Lead with the answer instead of a chronology dump
- Group findings by outcomes, decisions, and implications
- Always surface material open issues
- End with one concrete next step

### Better signal for non-technical readers

- Default audience is a non-technical decision-maker
- Keeps jargon low and evidence cues light
- Stays concise enough to scan quickly

### Reusable across tools

- Claude Code wrapper for custom Claude skills
- Codex wrapper for `.agents/skills`
- Shared authoring source so both stay aligned

---

## Getting Started

Clone the repository:

```bash
git clone https://github.com/fengwang/development-story-report-skill.git
cd development-story-report-skill
```

### Install for Claude Code

Global install:

```bash
mkdir -p ~/.claude/skills
cp -r claude/development-story-report ~/.claude/skills/
```

Project-level install:

```bash
mkdir -p .claude/skills
cp -r claude/development-story-report .claude/skills/
```

### Install for Codex

Global install:

```bash
mkdir -p ~/.agents/skills
cp -r .agents/skills/development-story-report ~/.agents/skills/
```

Project-level install:

```bash
mkdir -p .agents/skills
cp -r .agents/skills/development-story-report .agents/skills/
```

Codex currently scans `.agents/skills` from the current working directory up to the repository root, and also supports user-level skills in `~/.agents/skills`. Source: [OpenAI Codex Skills](https://developers.openai.com/codex/skills).

---

## Example Prompts

Once installed, prompts like these should trigger the skill naturally:

- `Wrap this up for leadership.`
- `Summarize what we found and what remains unresolved.`
- `Give me a short handoff note from this work.`
- `What changed here, in plain English?`
- `Create a development story report from this session.`

The default output is:

- Inline Markdown
- About 300-500 words
- Written for a non-technical decision-maker
- Structured as bottom line, key outcomes, open issues, and next step

---

## Repository Layout

```text
claude/
  development-story-report/         Generated Claude Code wrapper

.agents/
  skills/
    development-story-report/       Generated Codex wrapper

skill-src/
  shared/                           Shared content fragments
  wrappers/                         Wrapper-specific metadata and intros

src/development_story_report_tooling/
  builder.py                        Wrapper generation
  validation.py                     Smoke validation helpers

scripts/
  build_skill_wrappers.py           Build and validate both wrappers

evals/
  development-story-report-evals.json

dev-docs/
  design/
  plan/
  tasks/
  progress/
  findings/
```

---

## Development Docs

The repo’s implementation history and working documents live under [`dev-docs/`](./dev-docs):

- [`dev-docs/design/`](./dev-docs/design)
- [`dev-docs/plan/`](./dev-docs/plan)
- [`dev-docs/tasks/`](./dev-docs/tasks)
- [`dev-docs/progress/`](./dev-docs/progress)
- [`dev-docs/findings/`](./dev-docs/findings)

The repo also includes a self-generated wrap-up report in [`docs/`](./docs).

---

## Contributing

If you update the shared reporting method:

1. Edit the shared source in [`skill-src/`](./skill-src)
2. Run the unit tests
3. Rebuild the generated wrappers
4. Review the emitted `SKILL.md` files in [`claude/`](./claude) and [`.agents/`](./.agents)

This repo intentionally favors a clean generated-source model over manual duplication or compatibility layers.

---

## License

This repository is MIT-licensed. See [LICENSE](./LICENSE).